Skip to content

Request a payout

Last updated: 10th August 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

    HeaderValue

    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 nameDescription

      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

        1
        2
        3
        4
        5
        6
        7
        8
        9
        10
        11
        12
        13
        14
        15
        16
        17
        18
        19
        20
        21
        22
        23
        24
        25
        26
        {
        "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

          1
          2
          3
          4
          5
          6
          7
          8
          9
          10
          11
          12
          13
          14
          15
          16
          {
          "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

            1
            2
            3
            4
            5
            6
            7
            8
            9
            10
            11
            12
            13
            14
            15
            16
            17
            18
            19
            20
            21
            22
            23
            24
            25
            26
            27
            28
            29
            30
            31
            32
            33
            34
            35
            36
            {
            "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"
            }
            }
            }