Outbound Payment

View as Markdown

Outbound Payments represent payments sent from creditors.

GoCardless will notify you via a webhook when the status of the outbound payment changes.

Rate limiting

Two rate limits apply to the Outbound Payments APIs:

All POST Outbound Payment endpoints (create, withdraw, approve, cancel and etc.) share a single rate-limit group of 300 requests per minute. As initiating a payment typically requires two API calls (one to create the payment and one to approve it), this allows you to add approximately 150 outbound payments per minute.
All remaining Outbound Payment endpoints are limited to 500 requests per minute.

Create an outbound payment#

POST/outbound_payments

HTTPRubyPythonJavaScriptPHPJavaGo.NET

POST https://api.gocardless.com/outbound_payments HTTP/1.1
Content-Type: application/json
{
  "outbound_payments": {
    "amount": 10,
    "scheme": "faster_payments",
    "description": "Reward Payment (August 2024)",
    "links": {
      "recipient_bank_account": "BA12343",
      "creditor": "CR123"
    }
  }
}

@client.outbound_payments.create(
  params: {
    amount: 1000,
    scheme: "faster_payments",
    description: "Reward Payment (August 2024)",
    reference: "Invoice 123",
    links: {
      creditor: "CR123",
      recipient_bank_account: "BA123"
    }
  }
)

client.outbound_payments.create(params={
  "amount": 1000,
  "scheme": "faster_payments",
  "description": "Reward Payment (August 2024)",
  "reference": "Invoice 123",
  "links": {
    "creditor": "CR123",
    "recipient_bank_account": "BA123"
  }
})

const outboundPayment = await client.outboundPayments.create({
  amount: 1000,
  scheme: "faster_payments",
  description: "Reward Payment (August 2024)",
  reference: "Invoice 123",
  links: {
    creditor: "CR123",
    recipient_bank_account: "BA123"
  }
});

$client->outboundPayments()->create([
  "params" => [
    "amount" => 1000,
    "scheme" => "faster_payments",
    "description" => "Reward Payment (August 2024)",
    "reference" => "Invoice 123",
    "links" => [
      "creditor" => "CR123",
      "recipient_bank_account" => "BA123"
    ]
  ]
]);

import com.gocardless.services.OutboundPaymentService.OutboundPaymentCreateRequest.Scheme;

OutboundPayment outboundPayment = client.outboundPayments().create()
  .withAmount(1000)
  .withScheme(Scheme.FASTER_PAYMENTS)
  .withDescription("Reward Payment (August 2024)")
  .withReference("Invoice 123")
  .withLinksCreditor("CR123")
  .withLinksRecipientBankAccount("BA123")
  .execute();

outboundPaymentCreateParams := gocardless.OutboundPaymentCreateParams{
  Amount: 1000,
  Scheme: "faster_payments",
  Description: "Reward Payment (August 2024)",
  Reference: "Invoice 123",
  Links: gocardless.OutboundPaymentCreateParamsLinks{
    Creditor: "CR123",
    RecipientBankAccount: "BA123",
  },
}

outboundPayment, err := client.OutboundPayments.Create(ctx, outboundPaymentCreateParams)

var paymentLinks = new GoCardless.Services.OutboundPaymentCreateRequest.OutboundPaymentLinks
{
  Creditor = "CR123",
  RecipientBankAccount = "BA123"
};

var resp = await client.OutboundPayments.CreateAsync(
  new GoCardless.Services.OutboundPaymentCreateRequest()
  {
    Amount = 1000,
    Scheme = GoCardless.Services.OutboundPaymentCreateRequest.OutboundPaymentScheme.FasterPayments,
    Description = "Reward Payment (August 2024)",
    Reference = "Invoice 123",
    Links = paymentLinks,
  }
);

GoCardless.Resources.OutboundPayment outboundPayment = resp.OutboundPayment;

Responsehttp

HTTP/1.1 201 Created
Content-Type: application/json
{
  "outbound_payments": {
    "id": "OUT123",
    "created_at": "2024-09-05T12:20:04.397Z",
    "status": "pending_approval",
    "amount": 10,
    "scheme": "faster_payments",
    "currency": "GBP",
    "description": "Reward Payment (August 2024)",
    "execution_date": "2024-09-05",
    "reference": "GC-QC2FI7GBEW7VCXL",
    "is_withdrawal": false,
    "links": {
      "creditor": "CR123",
      "recipient_bank_account": "BA123"
    },
    "verifications": {
      "recipient_bank_account_holder_verification": {
        "result": "full_match",
        "type": "confirmation_of_payee",
        "actual_account_name": null
      }
    },
    "metadata": {}
  }
}

Request Body

outbound_paymentsobject

7 properties

amountinteger

Amount, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

schemestring

Bank payment scheme to process the outbound payment. Currently only "faster_payments" (GBP) is supported.

faster_payments

descriptionstring

A human-readable description of the outbound payment

execution_datestring

A future date on which the outbound payment should be sent. If not specified, the payment will be sent as soon as possible.

metadataobject

Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.

referencestring

An optional reference that will appear on your customer's bank statement. The character limit for this reference is dependent on the scheme.
Faster Payments - 18 characters, including: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789 &-./"

linksobject

3 properties

creditorstring

ID of the creditor who sends the outbound payment.

recipient_bank_accountstring

ID of the customer bank account which receives the outbound payment.

outbound_payment_importstring

ID of the outbound payment import that created this outbound payment.

Response 201

Resource created successfully

outbound_paymentsobject

13 properties

idstring

Unique identifier of the outbound payment.

created_atstring

Fixed timestamp, recording when the outbound payment was created.

statusstring

One of:

verifying: The payment has been created and the verification process has begun.
pending_approval: The payment is awaiting approval.
scheduled: The payment has passed verification & approval, but processing has not yet begun.
executing: The execution date has arrived and the payment has been placed in queue for processing.
executed: The payment has been accepted by the scheme and is now on its way to the recipient.
cancelled: The payment has been cancelled or was not approved on time.
failed: The payment was not sent, usually due to an error while or after executing.

verifyingpending_approvalscheduledexecutingexecutedcancelledfailed

amountinteger

Amount, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

schemestring

Bank payment scheme to process the outbound payment. Currently only "faster_payments" (GBP) is supported.

faster_payments

currencystring

ISO 4217 currency. Currently only "GBP" is supported.

GBP

execution_datestring

A future date on which the outbound payment should be sent. If not specified, the payment will be sent as soon as possible.

descriptionstring

A human-readable description of the outbound payment

referencestring

is_withdrawalboolean

Indicates whether the outbound payment is a withdrawal to your verified business bank account.

linksobject

4 properties

creditorstring

ID of the creditor who sends the outbound payment.

customerstring

ID of the customer that receives this outbound payment

recipient_bank_accountstring

ID of the customer bank account which receives the outbound payment.

outbound_payment_importstring

ID of the outbound payment import that created this outbound payment.

verificationsobject

Contains details of the verifications performed for the outbound payment

1 properties

recipient_bank_account_holder_verificationobject

Checks if the recipient owns the provided bank account

3 properties

typestring

Type of the verification that has been performed eg. Confirmation of Payee

confirmation_of_payee

resultstring

Result of the verification, could be one of

full_match: The verification has confirmed that the account name exactly matches the details provided.
partial_match: The verification has confirmed that the account name is similar but does not match to the details provided.
no_match: The verification concludes the provided name does not match the account details.
unable_to_match: The verification could not be performed due to recipient bank issues or technical issues

full_matchpartial_matchno_matchunable_to_match

actual_account_namestring

The actual account name returned by the recipient's bank, populated only in the case of a partial match.

metadataobject

Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.

Errors 400401404422500

400

Bad Request

401

Unauthorised

404

Not found

422

Validation Error

500

Internal Error

Error Body

codeinteger

documentation_urlstring

errorsarray

2 properties

reasonstring

messagestring

request_idstring

typestring

metadataobject

linksobject

List outbound payments#

GET/outbound_payments

Returns a cursor-paginated list of outbound payments.

HTTPRubyPythonJavaScriptPHPJavaGo.NET

GET https://api.gocardless.com/outbound_payments HTTP/1.1

@client.outbound_payments.list(params: { limit: 10 })

client.outbound_payments.list(params={"limit": 10})

const resp = await client.outboundPayments.list({
  limit: "10"
});

$client->outboundPayments()->list([
  "params" => ["limit" => 10]
]);

client.outboundPayments().list()
  .withLimit(10)
  .execute();

outboundPaymentListParams := gocardless.OutboundPaymentListParams{
  Limit: 10,
}

outboundPaymentListResult, err := client.OutboundPayments.List(ctx, outboundPaymentListParams)

var request = new GoCardless.Services.OutboundPaymentListRequest()
{
  Limit = 10
};

var resp = await client.OutboundPayments.ListAsync(request);

Responsehttp

HTTP/1.1 200 OK
Content-Type: application/json
{
  "meta": {
    "cursors": {
      "before": null,
      "after": null
    },
    "limit": 50
  },
  "outbound_payments": [{
    "id": "OUT123",
    "created_at": "2024-09-05T12:20:04.397Z",
    "status": "cancelled",
    "amount": 10,
    "scheme": "faster_payments",
    "currency": "GBP",
    "description": "Reward Payment (August 2024)",
    "execution_date": "2024-09-05",
    "reference": "GC-QC2FI7GBEW7VCXL",
    "is_withdrawal": false,
    "links": {
      "creditor": "CR123",
      "recipient_bank_account": "BA123"
    },
    "verifications": {
      "recipient_bank_account_holder_verification": {
        "result": "full_match",
        "type": "confirmation_of_payee",
        "actual_account_name": null
      }
    },
    "metadata": {}
  }]
}

Response 200

Successful response

outbound_paymentsarray

13 properties

idstring

Unique identifier of the outbound payment.

created_atstring

Fixed timestamp, recording when the outbound payment was created.

statusstring

One of:

verifying: The payment has been created and the verification process has begun.
pending_approval: The payment is awaiting approval.
scheduled: The payment has passed verification & approval, but processing has not yet begun.
executing: The execution date has arrived and the payment has been placed in queue for processing.
executed: The payment has been accepted by the scheme and is now on its way to the recipient.
cancelled: The payment has been cancelled or was not approved on time.
failed: The payment was not sent, usually due to an error while or after executing.

verifyingpending_approvalscheduledexecutingexecutedcancelledfailed

amountinteger

Amount, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

schemestring

Bank payment scheme to process the outbound payment. Currently only "faster_payments" (GBP) is supported.

faster_payments

currencystring

ISO 4217 currency. Currently only "GBP" is supported.

GBP

execution_datestring

A future date on which the outbound payment should be sent. If not specified, the payment will be sent as soon as possible.

descriptionstring

A human-readable description of the outbound payment

referencestring

is_withdrawalboolean

Indicates whether the outbound payment is a withdrawal to your verified business bank account.

linksobject

4 properties

creditorstring

ID of the creditor who sends the outbound payment.

customerstring

ID of the customer that receives this outbound payment

recipient_bank_accountstring

ID of the customer bank account which receives the outbound payment.

outbound_payment_importstring

ID of the outbound payment import that created this outbound payment.

verificationsobject

Contains details of the verifications performed for the outbound payment

1 properties

recipient_bank_account_holder_verificationobject

Checks if the recipient owns the provided bank account

3 properties

typestring

Type of the verification that has been performed eg. Confirmation of Payee

confirmation_of_payee

resultstring

Result of the verification, could be one of

full_match: The verification has confirmed that the account name exactly matches the details provided.
partial_match: The verification has confirmed that the account name is similar but does not match to the details provided.
no_match: The verification concludes the provided name does not match the account details.
unable_to_match: The verification could not be performed due to recipient bank issues or technical issues

full_matchpartial_matchno_matchunable_to_match

actual_account_namestring

The actual account name returned by the recipient's bank, populated only in the case of a partial match.

metadataobject

Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.

metaobject

2 properties

limitinteger

cursorsobject

2 properties

beforestring

Cursor pointing to the end of the desired set.

afterstring

Cursor pointing to the start of the desired set.

Errors 400401404422500

400

Bad Request

401

Unauthorised

404

Not found

422

Validation Error

500

Internal Error

Error Body

codeinteger

documentation_urlstring

errorsarray

2 properties

reasonstring

messagestring

request_idstring

typestring

metadataobject

linksobject

Create a withdrawal outbound payment#

POST/outbound_payments/withdrawal

Creates an outbound payment to your verified business bank account as the recipient.

HTTPRubyPythonJavaScriptPHPJavaGo.NET

POST https://api.gocardless.com/outbound_payments/withdrawal HTTP/1.1
Content-Type: application/json
{
  "outbound_payments": {
    "amount": 10,
    "scheme": "faster_payments",
    "description": "Withdraw funds to business account."
  }
}

@client.outbound_payments.withdraw(
  params: {
    amount: 5000,
    scheme: "faster_payments",
    description: "Withdraw funds to business account",
    links: {
      creditor: "CR123"
    }
  }
)

client.outbound_payments.withdraw(params={
  "amount": 5000,
  "scheme": "faster_payments",
  "description": "Withdraw funds to business account",
  "links": {
    "creditor": "CR123"
  }
})

const outboundPayment = await client.outboundPayments.withdraw({
  amount: 5000,
  scheme: "faster_payments",
  description: "Withdraw funds to business account",
  links: {
    creditor: "CR123"
  }
});

$client->outboundPayments()->withdraw([
  "params" => [
    "amount" => 5000,
    "scheme" => "faster_payments",
    "description" => "Withdraw funds to business account",
    "links" => [
      "creditor" => "CR123"
    ]
  ]
]);

import com.gocardless.services.OutboundPaymentService.OutboundPaymentWithdrawRequest.Scheme;

OutboundPayment outboundPayment = client.outboundPayments().withdraw()
  .withAmount(5000)
  .withScheme(Scheme.FASTER_PAYMENTS)
  .withDescription("Withdraw funds to business account")
  .withLinksCreditor("CR123")
  .execute();

outboundPaymentWithdrawParams := gocardless.OutboundPaymentWithdrawParams{
  Amount: 5000,
  Scheme: "faster_payments",
  Description: "Withdraw funds to business account",
  Links: &gocardless.OutboundPaymentWithdrawParamsLinks{
    Creditor: "CR123",
  },
}

outboundPayment, err := client.OutboundPayments.Withdraw(ctx, outboundPaymentWithdrawParams)

var paymentLinks = new GoCardless.Services.OutboundPaymentWithdrawRequest.OutboundPaymentLinks
{
  Creditor = "CR123"
};

var resp = await client.OutboundPayments.WithdrawAsync(
  new GoCardless.Services.OutboundPaymentWithdrawRequest()
  {
    Amount = 5000,
    Scheme = GoCardless.Services.OutboundPaymentWithdrawRequest.OutboundPaymentScheme.FasterPayments,
    Description = "Withdraw funds to business account",
    Links = paymentLinks,
  }
);

GoCardless.Resources.OutboundPayment outboundPayment = resp.OutboundPayment;

Responsehttp

HTTP/1.1 201 Created
Content-Type: application/json
{
  "outbound_payments": {
    "id": "OUT123",
    "created_at": "2024-09-05T12:20:04.397Z",
    "status": "pending_approval",
    "amount": 10,
    "scheme": "faster_payments",
    "currency": "GBP",
    "description": "Withdraw funds to business account.",
    "execution_date": "2024-09-05",
    "reference": "GC-QC2FI7GBEW7VCXL",
    "is_withdrawal": true,
    "verifications": {
      "recipient_bank_account_holder_verification": null
    },
    "links": {
      "creditor": "CR123",
      "recipient_bank_account": "BA123"
    },
    "metadata": {}
  }
}

Request Body

outbound_paymentsobject

7 properties

amountinteger

Amount, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

schemestring

Bank payment scheme to process the outbound payment. Currently only "faster_payments" (GBP) is supported.

faster_payments

descriptionstring

A human-readable description of the outbound payment

execution_datestring

A future date on which the outbound payment should be sent. If not specified, the payment will be sent as soon as possible.

metadataobject

Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.

referencestring

linksobject

1 properties

creditorstring

ID of the creditor who sends the outbound payment.

Response 201

Resource created successfully

outbound_paymentsobject

13 properties

idstring

Unique identifier of the outbound payment.

created_atstring

Fixed timestamp, recording when the outbound payment was created.

statusstring

One of:

verifying: The payment has been created and the verification process has begun.
pending_approval: The payment is awaiting approval.
scheduled: The payment has passed verification & approval, but processing has not yet begun.
executing: The execution date has arrived and the payment has been placed in queue for processing.
executed: The payment has been accepted by the scheme and is now on its way to the recipient.
cancelled: The payment has been cancelled or was not approved on time.
failed: The payment was not sent, usually due to an error while or after executing.

verifyingpending_approvalscheduledexecutingexecutedcancelledfailed

amountinteger

Amount, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

schemestring

Bank payment scheme to process the outbound payment. Currently only "faster_payments" (GBP) is supported.

faster_payments

currencystring

ISO 4217 currency. Currently only "GBP" is supported.

GBP

execution_datestring

A future date on which the outbound payment should be sent. If not specified, the payment will be sent as soon as possible.

descriptionstring

A human-readable description of the outbound payment

referencestring

is_withdrawalboolean

Indicates whether the outbound payment is a withdrawal to your verified business bank account.

linksobject

4 properties

creditorstring

ID of the creditor who sends the outbound payment.

customerstring

ID of the customer that receives this outbound payment

recipient_bank_accountstring

ID of the customer bank account which receives the outbound payment.

outbound_payment_importstring

ID of the outbound payment import that created this outbound payment.

verificationsobject

Contains details of the verifications performed for the outbound payment

1 properties

recipient_bank_account_holder_verificationobject

Checks if the recipient owns the provided bank account

3 properties

typestring

Type of the verification that has been performed eg. Confirmation of Payee

confirmation_of_payee

resultstring

Result of the verification, could be one of

full_match: The verification has confirmed that the account name exactly matches the details provided.
partial_match: The verification has confirmed that the account name is similar but does not match to the details provided.
no_match: The verification concludes the provided name does not match the account details.
unable_to_match: The verification could not be performed due to recipient bank issues or technical issues

full_matchpartial_matchno_matchunable_to_match

actual_account_namestring

The actual account name returned by the recipient's bank, populated only in the case of a partial match.

metadataobject

Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.

Errors 400401404422500

400

Bad Request

401

Unauthorised

404

Not found

422

Validation Error

500

Internal Error

Error Body

codeinteger

documentation_urlstring

errorsarray

2 properties

reasonstring

messagestring

request_idstring

typestring

metadataobject

linksobject

Cancel an outbound payment#

POST/outbound_payments/{outbound_payment_id}/actions/cancel

Cancels an outbound payment. Only outbound payments with either verifying, pending_approval, or scheduled status can be cancelled. Once an outbound payment is executing, the money moving process has begun and cannot be reversed.

Path Parameters

Name	Type	Description
`outbound_payment_id`required	string	The outbound payment id

HTTPRubyPythonJavaScriptPHPJavaGo.NET

POST https://api.gocardless.com/outbound_payments/OUT123/actions/cancel

@client.outbound_payments.cancel("OUT123")

client.outbound_payments.cancel("OUT123")

const resp = await client.outboundPayments.cancel("OUT123");

$client->outboundPayments()->cancel("OUT123");

client.outboundPayments().cancel("OUT123").execute();

outboundPayment, err := client.OutboundPayments.Cancel(ctx, "OUT123", gocardless.OutboundPaymentCancelParams{})

var resp = await client.OutboundPayments.CancelAsync("OUT123");

Responsehttp

HTTP/1.1 200
Content-Type: application/json
{
  "outbound_payments": {
    "id": "OUT123",
    "created_at": "2024-09-05T12:20:04.397Z",
    "status": "cancelled",
    "amount": 10,
    "scheme": "faster_payments",
    "currency": "GBP",
    "description": "Reward Payment (August 2024)",
    "execution_date": "2024-09-05",
    "reference": "GC-QC2FI7GBEW7VCXL",
    "is_withdrawal": false,
    "links": {
      "creditor": "CR123",
      "recipient_bank_account": "BA123"
    },
    "verifications": {
      "recipient_bank_account_holder_verification": {
        "result": "full_match",
        "type": "confirmation_of_payee",
        "actual_account_name": null
      }
    },
    "metadata": {}
  }
}

Request Body

outbound_paymentsobject

1 properties

metadataobject

Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.

Response 200

Action completed successfully

outbound_paymentsobject

13 properties

idstring

Unique identifier of the outbound payment.

created_atstring

Fixed timestamp, recording when the outbound payment was created.

statusstring

One of:

verifying: The payment has been created and the verification process has begun.
pending_approval: The payment is awaiting approval.
scheduled: The payment has passed verification & approval, but processing has not yet begun.
executing: The execution date has arrived and the payment has been placed in queue for processing.
executed: The payment has been accepted by the scheme and is now on its way to the recipient.
cancelled: The payment has been cancelled or was not approved on time.
failed: The payment was not sent, usually due to an error while or after executing.

verifyingpending_approvalscheduledexecutingexecutedcancelledfailed

amountinteger

Amount, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

schemestring

Bank payment scheme to process the outbound payment. Currently only "faster_payments" (GBP) is supported.

faster_payments

currencystring

ISO 4217 currency. Currently only "GBP" is supported.

GBP

execution_datestring

A future date on which the outbound payment should be sent. If not specified, the payment will be sent as soon as possible.

descriptionstring

A human-readable description of the outbound payment

referencestring

is_withdrawalboolean

Indicates whether the outbound payment is a withdrawal to your verified business bank account.

linksobject

4 properties

creditorstring

ID of the creditor who sends the outbound payment.

customerstring

ID of the customer that receives this outbound payment

recipient_bank_accountstring

ID of the customer bank account which receives the outbound payment.

outbound_payment_importstring

ID of the outbound payment import that created this outbound payment.

verificationsobject

Contains details of the verifications performed for the outbound payment

1 properties

recipient_bank_account_holder_verificationobject

Checks if the recipient owns the provided bank account

3 properties

typestring

Type of the verification that has been performed eg. Confirmation of Payee

confirmation_of_payee

resultstring

Result of the verification, could be one of

full_match: The verification has confirmed that the account name exactly matches the details provided.
partial_match: The verification has confirmed that the account name is similar but does not match to the details provided.
no_match: The verification concludes the provided name does not match the account details.
unable_to_match: The verification could not be performed due to recipient bank issues or technical issues

full_matchpartial_matchno_matchunable_to_match

actual_account_namestring

The actual account name returned by the recipient's bank, populated only in the case of a partial match.

metadataobject

Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.

Errors 400401404422500

400

Bad Request

401

Unauthorised

404

Not found

422

Validation Error

500

Internal Error

Error Body

codeinteger

documentation_urlstring

errorsarray

2 properties

reasonstring

messagestring

request_idstring

typestring

metadataobject

linksobject

Approve an outbound payment#

POST/outbound_payments/{outbound_payment_id}/actions/approve

Approves an outbound payment. Only outbound payments with the "pending_approval" status can be approved.

Path Parameters

Name	Type	Description
`outbound_payment_id`required	string	The outbound payment id

HTTPRubyPythonJavaScriptPHPJavaGo.NET

POST https://api.gocardless.com/outbound_payments/OUT123/actions/approve

@client.outbound_payments.approve("OUT123")

client.outbound_payments.approve("OUT123")

const resp = await client.outboundPayments.approve("OUT123");

$client->outboundPayments()->approve("OUT123");

client.outboundPayments().approve("OUT123").execute();

outboundPayment, err := client.OutboundPayments.Approve(ctx, "OUT123", gocardless.OutboundPaymentApproveParams{})

var resp = await client.OutboundPayments.ApproveAsync("OUT123");

Responsehttp

HTTP/1.1 200
Content-Type: application/json
{
  "outbound_payments": {
    "id": "OUT123",
    "created_at": "2024-09-05T12:20:04.397Z",
    "status": "scheduled",
    "amount": 10,
    "scheme": "faster_payments",
    "currency": "GBP",
    "description": "Reward Payment (August 2024)",
    "execution_date": "2024-09-05",
    "reference": "GC-QC2FI7GBEW7VCXL",
    "is_withdrawal": false,
    "links": {
      "creditor": "CR123",
      "recipient_bank_account": "BA123"
    },
    "verifications": {
      "recipient_bank_account_holder_verification": {
        "result": "full_match",
        "type": "confirmation_of_payee",
        "actual_account_name": null
      }
    },
    "metadata": {}
  }
}

Request Body

outbound_paymentsobject

0 properties

Response 200

Action completed successfully

outbound_paymentsobject

13 properties

idstring

Unique identifier of the outbound payment.

created_atstring

Fixed timestamp, recording when the outbound payment was created.

statusstring

One of:

verifying: The payment has been created and the verification process has begun.
pending_approval: The payment is awaiting approval.
scheduled: The payment has passed verification & approval, but processing has not yet begun.
executing: The execution date has arrived and the payment has been placed in queue for processing.
executed: The payment has been accepted by the scheme and is now on its way to the recipient.
cancelled: The payment has been cancelled or was not approved on time.
failed: The payment was not sent, usually due to an error while or after executing.

verifyingpending_approvalscheduledexecutingexecutedcancelledfailed

amountinteger

Amount, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

schemestring

Bank payment scheme to process the outbound payment. Currently only "faster_payments" (GBP) is supported.

faster_payments

currencystring

ISO 4217 currency. Currently only "GBP" is supported.

GBP

execution_datestring

A future date on which the outbound payment should be sent. If not specified, the payment will be sent as soon as possible.

descriptionstring

A human-readable description of the outbound payment

referencestring

is_withdrawalboolean

Indicates whether the outbound payment is a withdrawal to your verified business bank account.

linksobject

4 properties

creditorstring

ID of the creditor who sends the outbound payment.

customerstring

ID of the customer that receives this outbound payment

recipient_bank_accountstring

ID of the customer bank account which receives the outbound payment.

outbound_payment_importstring

ID of the outbound payment import that created this outbound payment.

verificationsobject

Contains details of the verifications performed for the outbound payment

1 properties

recipient_bank_account_holder_verificationobject

Checks if the recipient owns the provided bank account

3 properties

typestring

Type of the verification that has been performed eg. Confirmation of Payee

confirmation_of_payee

resultstring

Result of the verification, could be one of

full_match: The verification has confirmed that the account name exactly matches the details provided.
partial_match: The verification has confirmed that the account name is similar but does not match to the details provided.
no_match: The verification concludes the provided name does not match the account details.
unable_to_match: The verification could not be performed due to recipient bank issues or technical issues

full_matchpartial_matchno_matchunable_to_match

actual_account_namestring

The actual account name returned by the recipient's bank, populated only in the case of a partial match.

metadataobject

Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.

Errors 400401404422500

400

Bad Request

401

Unauthorised

404

Not found

422

Validation Error

500

Internal Error

Error Body

codeinteger

documentation_urlstring

errorsarray

2 properties

reasonstring

messagestring

request_idstring

typestring

metadataobject

linksobject

Get an outbound payment#

GET/outbound_payments/{outbound_payment_id}

Fetches an outbound_payment by ID

Path Parameters

Name	Type	Description
`outbound_payment_id`required	string	The outbound payment id

HTTPRubyPythonJavaScriptPHPJavaGo.NET

GET https://api.gocardless.com/outbound_payments/OUT123

@client.outbound_payments.get("OUT123")

client.outbound_payments.get("OUT123")

const resp = await client.outboundPayments.find("OUT123");

$client->outboundPayments()->get("OUT123");

client.outboundPayments().get("OUT123").execute();

outboundPayment, err := client.OutboundPayments.Get(ctx, "OUT123")

var resp = await client.OutboundPayments.GetAsync("OUT123");

Responsehttp

HTTP/1.1 200
Content-Type: application/json
{
  "outbound_payments": {
    "id": "OUT123",
    "created_at": "2024-09-05T12:20:04.397Z",
    "status": "scheduled",
    "amount": 10,
    "scheme": "faster_payments",
    "currency": "GBP",
    "description": "Reward Payment (August 2024)",
    "execution_date": "2024-09-05",
    "reference": "GC-QC2FI7GBEW7VCXL",
    "is_withdrawal": false,
    "links": {
      "creditor": "CR123",
      "recipient_bank_account": "BA123"
    },
    "verifications": {
      "recipient_bank_account_holder_verification": {
        "result": "full_match",
        "type": "confirmation_of_payee",
        "actual_account_name": null
      }
    },
    "metadata": {}
  }
}

Response 200

Successful response

outbound_paymentsobject

13 properties

idstring

Unique identifier of the outbound payment.

created_atstring

Fixed timestamp, recording when the outbound payment was created.

statusstring

One of:

verifying: The payment has been created and the verification process has begun.
pending_approval: The payment is awaiting approval.
scheduled: The payment has passed verification & approval, but processing has not yet begun.
executing: The execution date has arrived and the payment has been placed in queue for processing.
executed: The payment has been accepted by the scheme and is now on its way to the recipient.
cancelled: The payment has been cancelled or was not approved on time.
failed: The payment was not sent, usually due to an error while or after executing.

verifyingpending_approvalscheduledexecutingexecutedcancelledfailed

amountinteger

Amount, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

schemestring

Bank payment scheme to process the outbound payment. Currently only "faster_payments" (GBP) is supported.

faster_payments

currencystring

ISO 4217 currency. Currently only "GBP" is supported.

GBP

execution_datestring

A future date on which the outbound payment should be sent. If not specified, the payment will be sent as soon as possible.

descriptionstring

A human-readable description of the outbound payment

referencestring

is_withdrawalboolean

Indicates whether the outbound payment is a withdrawal to your verified business bank account.

linksobject

4 properties

creditorstring

ID of the creditor who sends the outbound payment.

customerstring

ID of the customer that receives this outbound payment

recipient_bank_accountstring

ID of the customer bank account which receives the outbound payment.

outbound_payment_importstring

ID of the outbound payment import that created this outbound payment.

verificationsobject

Contains details of the verifications performed for the outbound payment

1 properties

recipient_bank_account_holder_verificationobject

Checks if the recipient owns the provided bank account

3 properties

typestring

Type of the verification that has been performed eg. Confirmation of Payee

confirmation_of_payee

resultstring

Result of the verification, could be one of

full_match: The verification has confirmed that the account name exactly matches the details provided.
partial_match: The verification has confirmed that the account name is similar but does not match to the details provided.
no_match: The verification concludes the provided name does not match the account details.
unable_to_match: The verification could not be performed due to recipient bank issues or technical issues

full_matchpartial_matchno_matchunable_to_match

actual_account_namestring

The actual account name returned by the recipient's bank, populated only in the case of a partial match.

metadataobject

Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.

Errors 400401404422500

400

Bad Request

401

Unauthorised

404

Not found

422

Validation Error

500

Internal Error

Error Body

codeinteger

documentation_urlstring

errorsarray

2 properties

reasonstring

messagestring

request_idstring

typestring

metadataobject

linksobject

Update an outbound payment#

PUT/outbound_payments/{outbound_payment_id}

Updates an outbound payment object. This accepts only the metadata parameter.

Path Parameters

Name	Type	Description
`outbound_payment_id`required	string	The outbound payment id

HTTPRubyPythonJavaScriptPHPJavaGo.NET

PUT https://api.gocardless.com/outbound_payments/OUT123
Content-Type: application/json
{
  "outbound_payments": {
    "metadata": {
      "id": "1234"
    }
  }
}

@client.outbound_payments.update(
  "OUT123",
  params: {
    metadata: {
      invoice_id: "INV-1234"
    }
  }
)

client.outbound_payments.update("OUT123", params={
  "metadata": {
    "invoice_id": "INV-1234"
  }
})

const resp = await client.outboundPayments.update("OUT123", {
  metadata: {
    invoice_id: "INV-1234"
  }
});

$client->outboundPayments()->update("OUT123", [
  "params" => [
    "metadata" => [
      "invoice_id" => "INV-1234"
    ]
  ]
]);

OutboundPayment outboundPayment = client.outboundPayments().update("OUT123")
  .withMetadata("invoice_id", "INV-1234")
  .execute();

outboundPaymentUpdateParams := gocardless.OutboundPaymentUpdateParams{
  Metadata: map[string]string{
    "invoice_id": "INV-1234",
  },
}

outboundPayment, err := client.OutboundPayments.Update(ctx, "OUT123", outboundPaymentUpdateParams)

var metadata = new Dictionary<string, string>
{
  { "invoice_id", "INV-1234" }
};

var resp = await client.OutboundPayments.UpdateAsync(
  "OUT123",
  new GoCardless.Services.OutboundPaymentUpdateRequest()
  {
    Metadata = metadata,
  }
);

Responsehttp

HTTP/1.1 200
Content-Type: application/json
{
  "outbound_payments": {
    "id": "OUT123",
    "created_at": "2024-09-05T12:20:04.397Z",
    "status": "cancelled",
    "amount": 10,
    "scheme": "faster_payments",
    "currency": "GBP",
    "description": "Reward Payment (August 2024)",
    "execution_date": "2024-09-05",
    "reference": "GC-QC2FI7GBEW7VCXL",
    "is_withdrawal": false,
    "links": {
      "creditor": "CR123",
      "recipient_bank_account": "BA123"
    },
    "verifications": {
      "recipient_bank_account_holder_verification": {
        "result": "full_match",
        "type": "confirmation_of_payee",
        "actual_account_name": null
      }
    },
    "metadata": {
      "id": "1234"
    }
  }
}

Request Body

outbound_paymentsobject

1 properties

metadataobject

Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.

Response 200

Successful response

outbound_paymentsobject

13 properties

idstring

Unique identifier of the outbound payment.

created_atstring

Fixed timestamp, recording when the outbound payment was created.

statusstring

One of:

verifying: The payment has been created and the verification process has begun.
pending_approval: The payment is awaiting approval.
scheduled: The payment has passed verification & approval, but processing has not yet begun.
executing: The execution date has arrived and the payment has been placed in queue for processing.
executed: The payment has been accepted by the scheme and is now on its way to the recipient.
cancelled: The payment has been cancelled or was not approved on time.
failed: The payment was not sent, usually due to an error while or after executing.

verifyingpending_approvalscheduledexecutingexecutedcancelledfailed

amountinteger

Amount, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

schemestring

Bank payment scheme to process the outbound payment. Currently only "faster_payments" (GBP) is supported.

faster_payments

currencystring

ISO 4217 currency. Currently only "GBP" is supported.

GBP

execution_datestring

A future date on which the outbound payment should be sent. If not specified, the payment will be sent as soon as possible.

descriptionstring

A human-readable description of the outbound payment

referencestring

is_withdrawalboolean

Indicates whether the outbound payment is a withdrawal to your verified business bank account.

linksobject

4 properties

creditorstring

ID of the creditor who sends the outbound payment.

customerstring

ID of the customer that receives this outbound payment

recipient_bank_accountstring

ID of the customer bank account which receives the outbound payment.

outbound_payment_importstring

ID of the outbound payment import that created this outbound payment.

verificationsobject

Contains details of the verifications performed for the outbound payment

1 properties

recipient_bank_account_holder_verificationobject

Checks if the recipient owns the provided bank account

3 properties

typestring

Type of the verification that has been performed eg. Confirmation of Payee

confirmation_of_payee

resultstring

Result of the verification, could be one of

full_match: The verification has confirmed that the account name exactly matches the details provided.
partial_match: The verification has confirmed that the account name is similar but does not match to the details provided.
no_match: The verification concludes the provided name does not match the account details.
unable_to_match: The verification could not be performed due to recipient bank issues or technical issues

full_matchpartial_matchno_matchunable_to_match

actual_account_namestring

The actual account name returned by the recipient's bank, populated only in the case of a partial match.

metadataobject

Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.

Errors 400401404422500

400

Bad Request

401

Unauthorised

404

Not found

422

Validation Error

500

Internal Error

Error Body

codeinteger

documentation_urlstring

errorsarray

2 properties

reasonstring

messagestring

request_idstring

typestring

metadataobject

linksobject