Payment instruments

​

Manage bank account payment instruments for your sub-entities.

Payment instruments Operations

Get payment instrument details

​

Retrieve the details of a specific payment instrument used for sub-entity payouts.

Path Parameters
  • entityId
    Type: string
    required

    The sub-entity's ID.

  • id
    Type: string
    required

    The payment instrument's ID.

Responses
  • application/json
  • 400

    Bad Request

  • 401

    Unauthorized

Request Example for get/accounts/entities/{entityId}/payment-instruments/{id}
curl 'https://{prefix}.api.sandbox.checkout.com/accounts/entities/ent_w4jelhppmfiufdnatam37wrfc4/payment-instruments/ppi_qn4nis4k3ykpzzu7cvtuvhqqga' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "id": "ppi_qn4nis4k3ykpzzu7cvtuvhqqga",
  "label": "Bob's Bank Account",
  "type": "bank_account",
  "currency": "GBP",
  "country": "GB",
  "document": {
    "type": "bank_statement",
    "file_id": "file_wxglze3wwywujg4nna5fb7ldli"
  },
  "status": "verified",
  "instrument_id": "src_pdasnoaxrtoevpyh3opgaxcrti"
}

Payment instrument details

Update payment instrument details

​

Set an existing payment instrument as default. This will make it the destination instrument when a scheduled payout is made. You can also update the label of a payment instrument.

Path Parameters
  • entityId
    Type: string
    required

    The sub-entity's ID.

  • id
    Type: string
    required

    The payment instrument's ID.

Body·
required
application/json
  • label
    Type: string · Label
    min length:  
    1
    max length:  
    50

    A reference that you can use to identify the payment instrument.

  • default
    Type: boolean · Default
    deprecated

    For ad-hoc payouts, the payment instrument is explicitly specified in the payout request. For scheduled payouts, the first payment instrument created for a given currency will be used for that currency's payout schedule. To change the payment instrument associated with a payout schedule, update the payout schedule. (Deprecated) Specifies whether the payment instrument should be set as the default payout destination.

  • headers
    Type: object
Responses
  • application/json
  • 401

    Unauthorized

  • application/json
  • application/json
Request Example for patch/accounts/entities/{entityId}/payment-instruments/{id}
curl 'https://{prefix}.api.sandbox.checkout.com/accounts/entities/ent_w4jelhppmfiufdnatam37wrfc4/payment-instruments/ppi_qn4nis4k3ykpzzu7cvtuvhqqga' \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "label": "Peter'\''s Personal Account",
  "headers": {
    "if-match": "Y3Y9MCZydj0w"
  }
}'

{
  "_links": {
    "self": {
      "href": "https://{prefix}.api.checkout.com/accounts/entities/ent_wxglze3wwywujg4nna5fb7ldli"
    }
  },
  "id": "ppi_qn4nis4k3ykpzzu7cvtuvhqqga"
}

Payment instrument updated successfully

Add a payment instrument

​

Create a bank account payment instrument for your sub-entity. You can use this payment instrument as a payout destination.

Path Parameters
  • id
    Type: string
    required

    The sub-entity's ID.

Body·
required
application/json

A JSON payload containing the payment instrument details.

    Card Token Request

      • label
        Type: string · Label
        min length:  
        1
        max length:  
        50
        required

        A reference that you can use to identify the payment instrument

      • type
        Type: string · Typeenum
        required

        The instrument type

        values
        • bank_account
        • card_token
      • currency
        Type: string · Currency
        min length:  
        3
        max length:  
        3        Format: ISO 4217
        required

        The account's currency, as a 3-letter ISO currency code

      • instrument_details
        Type: object
        required

        Details of the payment instrument being created

Responses
  • application/json
  • 400

    Bad Request

  • 401

    Unauthorized

  • application/json
Request Example for post/accounts/entities/{id}/payment-instruments
curl 'https://{prefix}.api.sandbox.checkout.com/accounts/entities/ent_w4jelhppmfiufdnatam37wrfc4/payment-instruments' \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "label": "Bob'\''s Bank Account",
  "type": "bank_account",
  "currency": "GBP",
  "country": "GB",
  "instrument_details": {
    "account_number": "12345678",
    "bank_code": "050389"
  },
  "document": {
    "type": "bank_statement",
    "file_id": "file_wxglze3wwywujg4nna5fb7ldli"
  }
}'

{
  "id": "ppi_qn4nis4k3ykpzzu7cvtuvhqqga"
}

Created

Query payment instruments

​

Fetch all of the payment instruments for a sub-entity. You can filter by status to identify verified instruments that are ready to be used for Payouts.

Path Parameters
  • id
    Type: string
    required

    The sub-entity's ID.

Query Parameters
  • status
    Type: string · enum

    The status of your sub-entity's payment instrument. The status indicates the instrument's stage of verification, and whether it can be used for payouts.

    values
    • pending
    • verified
    • unverified
Responses
  • application/json
  • 400

    Bad Request

  • 401

    Unauthorized

Request Example for get/accounts/entities/{id}/payment-instruments
curl 'https://{prefix}.api.sandbox.checkout.com/accounts/entities/ent_w4jelhppmfiufdnatam37wrfc4/payment-instruments' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "data": [
    {
      "id": "ppi_qn4nis4k3ykpzzu7cvtuvhqqga",
      "label": "Bob's Bank Account",
      "type": "bank_account",
      "currency": "GBP",
      "country": "GB",
      "status": "verified",
      "instrument_id": "src_pdasnoaxrtoevpyh3opgaxcrti"
    },
    {
      "id": "ppi_yk7nmh5jypmqzw5kb6kshj2iiy",
      "label": "Bruno's Bank Account",
      "type": "bank_account",
      "currency": "EUR",
      "country": "FR",
      "status": "pending"
    }
  ]
}

OK