curl --request POST \
--url https://api-sandbox.finogates.com/v1/platform/payees/bank-accounts/{payee_id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"nickname": "Acme — Operating",
"account_holder_name": "Acme Supplier LLC",
"bank_name": "Example Bank",
"bank_country": "US",
"currency": "USD",
"bank_account_number": "000123456789",
"routing_number": "021000021",
"account_type": "checking"
}
'{
"status_code": 201,
"data": {
"id": "f1e2d3c4-b5a6-7890-1234-567890abcdef",
"payee_id": "d4e5f6a7-b8c9-0123-4567-890abcdef012",
"nickname": "Acme — Operating",
"account_holder_name": "Acme Supplier LLC",
"bank_name": "Example Bank",
"bank_country": "US",
"currency": "USD",
"rail_code": "ach",
"account_type": "checking",
"account_last4": "6789",
"routing_last4": "0021",
"status": "active",
"created_at": "2025-06-10T18:12:00.000Z",
"updated_at": "2025-06-10T18:12:00.000Z"
},
"query_generated_time": 1712847600000
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>"
}
]
}Add a Bank Account to a Payee
Save the bank account where this payee should receive money. One endpoint covers two cases — send the fields for whichever applies:
- US domestic (ACH) —
bank_account_numberplusrouting_number(9-digit, ABA-valid). Optionally addaccount_type(checkingorsavings). - International —
bank_account_numberplusbank_country(the ISO 3166-1 alpha-2 destination country, e.g.AE,IN,MX). The receiving bank’s routing identifier,bank_branch, varies by country (IFSC for India, CLABE for Mexico, SWIFT/BIC elsewhere) and is carried in one field instead of a column per country — it is optional: some corridors (e.g. UAE) need only the account number. The numericpayout_branch_idis also optional — if you omit it, it is resolved when a payout is sent (from the corridor’s country and currency). Addbank_name,bank_document,purpose_of_payment, andrecipient_typewhere the corridor requires them.
Individual fields are optional, but the body must satisfy one of the two cases above or the request is rejected.
Account and routing numbers are encrypted at rest — only the last four digits are ever returned (account_last4, routing_last4).
curl --request POST \
--url https://api-sandbox.finogates.com/v1/platform/payees/bank-accounts/{payee_id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"nickname": "Acme — Operating",
"account_holder_name": "Acme Supplier LLC",
"bank_name": "Example Bank",
"bank_country": "US",
"currency": "USD",
"bank_account_number": "000123456789",
"routing_number": "021000021",
"account_type": "checking"
}
'{
"status_code": 201,
"data": {
"id": "f1e2d3c4-b5a6-7890-1234-567890abcdef",
"payee_id": "d4e5f6a7-b8c9-0123-4567-890abcdef012",
"nickname": "Acme — Operating",
"account_holder_name": "Acme Supplier LLC",
"bank_name": "Example Bank",
"bank_country": "US",
"currency": "USD",
"rail_code": "ach",
"account_type": "checking",
"account_last4": "6789",
"routing_last4": "0021",
"status": "active",
"created_at": "2025-06-10T18:12:00.000Z",
"updated_at": "2025-06-10T18:12:00.000Z"
},
"query_generated_time": 1712847600000
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>"
}
]
}Authorizations
The access token received from the authorization server in the OAuth 2.0 flow.
Path Parameters
Query Parameters
The unique ID of the user who owns this payee.
"b3a9b622-cc63-4d3c-aad6-2d8e29e6f9d4"
Body
Request body for adding a bank account to a payee.
Every field is optional, but the combination must describe either:
- A US domestic account — set
bank_account_numberandrouting_number(a 9-digit US ABA-valid routing number); or - An international account — set
bank_account_numberandbank_country(the ISO 3166-1 alpha-2 destination country). The corridor's routing identifier —bank_branch(IFSC / CLABE / SWIFT-BIC / …) and the numericpayout_branch_id— is optional: some corridors (e.g. UAE) need only the account number, and where a branch is required it is resolved at payout time.
The endpoint rejects requests that satisfy neither case.
Optional short label your user gave this bank account (for example, "Acme — Chase Checking").
120The name on the bank account, exactly as the bank has it.
120The bank's name. Useful for international accounts.
120ISO 3166-1 alpha-2 country code of the bank (e.g. US, GB, DE).
2ISO 4217 three-letter currency code (e.g. USD, EUR, GBP). Defaults to USD when not provided.
3The bank account number where money will be deposited.
4 - 34US-only: the 9-digit ABA routing number of the bank.
9Account type — "checking"/"savings" for US ACH, or a corridor account-type code (AHO/CTE/NON) for international.
30Optional: a short description of why the money is being sent (some corridors require it).
120Optional: either "individual" or "business".
The receiving bank's routing identifier for an international payout. A single field that carries whatever the destination country uses — e.g. IFSC for India, CLABE for Mexico, or the SWIFT/BIC code elsewhere.
50Recipient bank document (e.g. CPF / CNPJ / RFC), where the corridor needs it.
100Optional numeric payout branch id for an international payout. If omitted, it is resolved at payout time from the destination's corridor (country + currency), so the account can be registered with just the routing code in bank_branch.
Response
The saved bank account (sensitive numbers masked).