Request a payout

Last updated: 14th July 2022

Make seamless payouts to your customer’s bank accounts with Bank Payouts. Access local clearing methods globally, circumventing the challenges of international payments and simplifying complex payment infrastructures.

You can send a payout in two ways: (1) use a bank account payment instrument that you have previously created and stored, or (2) use the bank account fields required for the country and currency to which you want to pay out funds.

Step 1: Get bank account field formatting

Before you can request a payout, you need to use the get bank account field formatting endpoint to retrieve the relevant bank account fields and formatting for the country and currency to which you'll be paying out.

Once you've done that, you can either use those bank account details directly in your payout request, or use them to create a reusable bank account payment instrument, which you can then use in your bank payout requests.

Step 2: Request a payout

Request a Bank Payout by using the relevant bank account fields or a bank account payment instrument (prefixed by src_). To get a detailed view of all required and optional fields, see our API reference.

Endpoints

post

https://api.checkout.com/payments

Header parameters

Header	Value
`Authorization` required	`OAuth Bearer access token`
`Content-Type` required	`application/json`
`Cko-Idempotency-Key` optional	An optional idempotency key for safely retrying payout requests.

Body parameters

See our API reference for the full specification.

Field name	Description
`source` required object	Details about the payout source.
`source.amount` conditional integer	The amount you want to pay out from your currency account. The exact format depends on the currency. You must specify either the `source.amount` or the destination `amount`.
`source.type` required string	The type of source. Set this to `currency_account`.
`source.id` required string	The source identifier. This is prefixed by `ca_`.
`destination` required object	Details about the payout destination.
`destination.type` required object	The type of payout destination. Set this to `id`. To create a bank account payment instrument, use our Instruments API.
`destination.id` required string	The bank account payment instrument identifier. This is prefixed by `src_`.
`amount` conditional integer(>=0)	The amount you want to pay out to the destination account. The exact format depends on the currency. You must specify either the destination `amount` or the `source.amount`.
`currency` required string (3 chars)	The three-letter ISO code of the destination currency. The currency should match that of the destination account.
`reference` optional string	An optional reference you can later use to identify this payout.
`billing_descriptor` required object	Details about the billing descriptor.
`billing_descriptor.reference` required string	The reference that is (where possible) displayed on the account holder's statement.
`sender` required object	Details about the sender of the payout's funds.
`sender.type` required string	The type of sender. This can be `instrument`, `individual`, or `corporate`.
`sender.address` required string	The sender's address.
`sender.reference` required string	The sender's unique ID.
`instruction` optional object	Details about the instruction for payouts to bank accounts.
`instruction.purpose` optional string	An optional description of the payout purpose, for example `Insurance claim` or `Remittance`.
`instruction.charge_bearer` optional string	Who should be charged the payout fee. This can be one of: `OUR` `SHA` Only applies to only to international payments.
`instruction.repair` optional boolean	Determines whether the payout details can be modified to attempt to prevent the payout from being returned.
`instruction.scheme` optional string (enum)	The preferred payment scheme or network the bank transfer will be sent through. This can be one of: `swift` `local` `instant` Bank details must be in line with the chosen scheme.
`instruction.quote_id` optional string (30 chars)	The FX quote identifier. If omitted, and the source and destination currencies differ, the current market exchange rate will be used. To create a quote, use our Foreign Exchange API.
`processing_channel_id` required string	The processing channel identifier.

Request example

{
  "source": {
    "type": "currency_account",
    "id": "ca_y3oqhf46pyzuxjbcn2giaqnb44"
  },
  "destination": {
    "type": "id",
    "id": "src_gsd2agaqd2sernz5tpcfv555nq"
  },
  "amount": 1000,
  "currency": "GBP",
  "reference": "PO-215-5721",
  "billing_descriptor": {
    "reference": "Withdrawal"
  },
  "sender": {
    "type": "instrument",
    "reference": "8285282045818"
  },
  "instruction": {
    "purpose": "Withdrawal",
    "scheme": "local",
    "quote_id": "qte_mbabizu24mvu3mela5njyhpit4"
  },
  "processing_channel_id": "pc_hpswyyx23geezflc2ocz3exn4y"
}

Response examples

If your payout request was successfully sent, you will receive a 202 response, with the status Pending. If your request was unsuccessful, you will receive a 422 or 429 response containing the error code.

You will then receive a webhook notification indicating the status of your payout

{
  "id": "pay_dvxl6j6stpqufkzfgbaahmfrzm",
  "status": "Pending",
  "reference": "PO-215-5721",
  "instruction": {
      "value_date": "2020-06-12T22:27:42.512594Z"
  },
  "_links": {
    "self": {
      "href": "https://api.sandbox.checkout.com/payments/pay_dvxl6j6stpqufkzfgbaahmfrzm"
    },
    "actions": {
      "href": "https://api.sandbox.checkout.com/payments/pay_dvxl6j6stpqufkzfgbaahmfrzm/actions"
    }
  }
}

Webhooks

After receiving the response to your payout request, you will get a webhook notification indicating the status of your payout:

If your payout is successful, you will receive a payment_paid webhook, with a 10000 response code and the Approved summary.
If your payout is declined, you will receive a payment_declined webhook with a 50001-50399 response code and a summary explaining the reason for the decline. You can view the list of response codes here.
If your payout is returned, you will receive a payment_returned webhook with 50401-50599 response code and a summary explaining the reason for the return. You can view the list of response codes here.

Use our testing guide to test different payout scenarios.

Webhook examples

{
  "id": "evt_ooratpvrc4yezkrjjrfohi26te",
  "type": "payment_paid",
  "version": "1.0.3",
  "created_on": "2020-06-12T17:46:24.4862402Z",
  "data": {
    "id": "pay_dvxl6j6stpqufkzfgbaahmfrzm",
    "reference": "PO-215-5721",
    "action_id": "act_y37vtskjeweuhfy4mhiggxhpgu",
    "response_code": "10000",
    "response_summary": "Approved",
    "amount": 1000,
    "currency": "GBP",
    "source": {
      "type": "currency_account",
      "id": "ca_y3oqhf46pyzuxjbcn2giaqnb44"
    },
    "destination": {
      "type": "bank_account",
      "id": "src_vovjchw6exauvjrdzpmfu3sm3y",
      "fingerprint": "vnsdrvikkvre3dtrjjvlm5du4q"
    },
    "processed_on": "2020-06-12T17:46:15.2106459Z",
    "instruction": {
      "value_date": "2020-06-13T05:46:15.2845092Z"
    }
  },
  "_links": {
    "self": {
      "href": "https://api.sandbox.checkout.com/workflows/events/evt_ooratpvrc4yezkrjjrfohi26te"
    },
    "subject": {
      "href": "https://api.sandbox.checkout.com/workflows/events/subject/pay_dvxl6j6stpqufkzfgbaahmfrzm"
    }
  }
}