---
title: "Retrieve top-up instructions"
method: GET
path: "/entities/{entityId}/currency-accounts/{currencyAccountId}/top-up-instructions"
tags: ["Balances"]
---

# Retrieve top-up instructions

`GET /entities/{entityId}/currency-accounts/{currencyAccountId}/top-up-instructions`

## Request

- Base URL: `https://balances.checkout.com`
- URL: `https://balances.checkout.com/entities/{entityId}/currency-accounts/{currencyAccountId}/top-up-instructions`
- Auth: one of:
  - OAuth 2
    - Client credentials
    - Token URL: `string` scopes: `balances`, `balances:top-up-instructions`
  - API key in header `Authorization`
- TypeScript: <https://skmtc.dev/checkout/apis/checkout-com-api-reference/docs/entities/:entityId/currency-accounts/:currencyAccountId/top-up-instructions/get.ts> (a function with typed inputs; its response is checked against the schema)

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. <br/>*Note:* The sub-account is referred to as _currency account_ in the API.

## Response `200`

Top-up instructions retrieved successfully.

- TopUpInstructionsResponse: The bank details and payment reference used to top up a sub-account.
  - `currency_account_id` string, required: The unique identifier of the sub-account that the instructions apply to.
  - `currency` string, required: The currency that funds must be sent in, as a three-letter <a href="https://www.checkout.com/docs/resources/codes/currency-codes" target="_blank">ISO 4217 currency code</a>. <br/><br/> This is the sub-account's holding currency, returned as `holding_currency` by the <a href="https://api-reference.checkout.com/#operation/getEntityBalances">Retrieve entity balances</a> endpoint.
  - `payment_reference` string, required: The reference that must be quoted on the payment. It is how an incoming payment is attributed to the sub-account. A payment sent without this reference may not be credited.
  - `bank_details` TopUpBankDetails, required: The bank details for each available funding rail. Both `domestic` and `international` are optional, and their availability depends on the sub-account's holding currency, jurisdiction, and banking partner. Do not assume that both rails are always available.
    - `domestic` TopUpFundingDetails: The bank details for a single funding rail. `beneficiary_account_name` and `bank_name` are the only fields always returned. The remaining fields vary by rail and the receiving bank's jurisdiction, and are omitted when they do not apply.
      - `beneficiary_account_name` string, required: The name of the account that receives the funds.
      - `beneficiary_address` string: The address of the beneficiary, if the rail requires it.
      - `bank_name` string, required: The name of the bank that receives the funds.
      - `bank_address` string: The address of the receiving bank, if the rail requires it.
      - `account_number` string: The account number of the receiving account.
      - `sort_code` string: The sort code of the receiving bank. Returned for United Kingdom domestic transfers.
      - `routing_number` string: The routing number of the receiving bank. Returned for United States domestic transfers.
      - `iban` string: The International Bank Account Number of the receiving account.
      - `swift_code` string: The SWIFT or BIC code of the receiving bank. Returned for international transfers.
    - `international` TopUpFundingDetails: The bank details for a single funding rail. `beneficiary_account_name` and `bank_name` are the only fields always returned. The remaining fields vary by rail and the receiving bank's jurisdiction, and are omitted when they do not apply.
      - `beneficiary_account_name` string, required: The name of the account that receives the funds.
      - `beneficiary_address` string: The address of the beneficiary, if the rail requires it.
      - `bank_name` string, required: The name of the bank that receives the funds.
      - `bank_address` string: The address of the receiving bank, if the rail requires it.
      - `account_number` string: The account number of the receiving account.
      - `sort_code` string: The sort code of the receiving bank. Returned for United Kingdom domestic transfers.
      - `routing_number` string: The routing number of the receiving bank. Returned for United States domestic transfers.
      - `iban` string: The International Bank Account Number of the receiving account.
      - `swift_code` string: The SWIFT or BIC code of the receiving bank. Returned for international transfers.

## Other responses

- `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.

---

[API](https://skmtc.dev/checkout/apis/checkout-com-api-reference.md) - [All operations](https://skmtc.dev/checkout/apis/checkout-com-api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/checkout/apis/checkout-com-api-reference/revisions/0f1abdb1c3e9?raw)