Retrieve top-up instructions

​

Use this endpoint to retrieve the bank details required to top up a sub-account, along with the payment reference that attributes an incoming payment to that sub-account.
Note: The sub-account is referred to as currency account in the API.

Path Parameters
  • entityId
    Type: string
    required

    The ID of the entity that owns the sub-account, or of an entity above it in your hierarchy. A platform can use its own entity ID to reach the sub-accounts of any entity beneath it.

  • currencyAccountId
    Type: string
    required

    The ID of the sub-account to retrieve top-up instructions for.

Responses
  • application/json
  • 400

    Invalid entityId or currencyAccountId.

  • 401

    Unauthorized

  • 403

    The credential lacks access to top-up instructions, or top-ups aren't enabled for the sub-account.

  • 404

    The specified sub-account could not be found, or has no top-up instructions available.

  • 502

    The request could not be completed. Try again later.

Request Example for get/entities/{entityId}/currency-accounts/{currencyAccountId}/top-up-instructions
Shell Curl
curl https://balances.checkout.com/entities/ent_w4jelhppmfiufdnatam37wrfc4/currency-accounts/ca_g5y7d6jo4e2urgforcbf2ey5jm/top-up-instructions \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "currency_account_id": "ca_g5y7d6jo4e2urgforcbf2ey5jm",
  "currency": "USD",
  "payment_reference": "TP-ABC123",
  "bank_details": {
    "domestic": {
      "beneficiary_account_name": "Acme Inc",
      "beneficiary_address": "1 Example Street, Exampleville, EX, 00000, US",
      "bank_name": "Example Bank",
      "bank_address": "1 Example Street, Exampleville, EX, 00000, US",
      "account_number": "1234567890",
      "sort_code": "000000",
      "routing_number": "000000000",
      "iban": "GB00EXAM00000000000000",
      "swift_code": "TESTUS00XXX"
    },
    "international": {
      "beneficiary_account_name": "Acme Inc",
      "beneficiary_address": "1 Example Street, Exampleville, EX, 00000, US",
      "bank_name": "Example Bank",
      "bank_address": "1 Example Street, Exampleville, EX, 00000, US",
      "account_number": "1234567890",
      "sort_code": "000000",
      "routing_number": "000000000",
      "iban": "GB00EXAM00000000000000",
      "swift_code": "TESTUS00XXX"
    }
  }
}

Top-up instructions retrieved successfully.