Skip to main content
POST
/
v1
/
platform
/
payees
/
bank-accounts
/
{payee_id}
Add a Bank Account to a Payee
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": "<string>",
  "account_holder_name": "<string>",
  "bank_name": "<string>",
  "bank_country": "<string>",
  "currency": "<string>",
  "bank_account_number": "<string>",
  "routing_number": "<string>",
  "account_type": "<string>",
  "swift_bic": "<string>",
  "iban": "<string>",
  "intermediary_bank_name": "<string>",
  "intermediary_swift_bic": "<string>",
  "purpose_of_payment": "<string>",
  "recipient_type": "<string>",
  "bank_branch": "<string>",
  "bank_document": "<string>",
  "payout_branch_id": 123
}
'
{
  "status_code": 123,
  "data": "<unknown>",
  "query_generated_time": 123
}

Authorizations

​
Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Path Parameters

​
payee_id
string<uuid>
required

Query Parameters

​
user_id
string<uuid>
required

The unique ID of the user who owns this payee.

Body

application/json

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_number and routing_number (a 9-digit US ABA-valid routing number); or
  • An international account — set swift_bic (8 or 11 characters) along with whatever the corridor needs (iban for SEPA / most of EMEA, bank_account_number for some others).

The endpoint rejects requests that satisfy neither case.

​
nickname
string | null

Optional short label your user gave this bank account (for example, "Acme — Chase Checking").

Maximum string length: 120
​
account_holder_name
string | null

The name on the bank account, exactly as the bank has it.

Maximum string length: 120
​
bank_name
string | null

The bank's name. Useful for international accounts.

Maximum string length: 120
​
bank_country
string | null

ISO 3166-1 alpha-2 country code of the bank (e.g. US, GB, DE).

Required string length: 2
​
currency
string | null

ISO 4217 three-letter currency code (e.g. USD, EUR, GBP). Defaults to USD when not provided.

Required string length: 3
​
bank_account_number
string | null

The bank account number where money will be deposited.

Required string length: 4 - 34
​
routing_number
string | null

US-only: the 9-digit ABA routing number of the bank.

Maximum string length: 9
​
account_type
string | null

Account type — "checking"/"savings" for US ACH, or the provider code for UniTeller.

Maximum string length: 30
​
swift_bic
string | null

International: the SWIFT/BIC code of the recipient's bank (8 or 11 characters).

Maximum string length: 11
​
iban
string | null

International: the IBAN of the recipient's account (15-34 characters, used by SEPA and most of EMEA).

Maximum string length: 34
​
intermediary_bank_name
string | null

Optional: the correspondent bank that routes funds to the recipient's bank (sometimes required for USD wires).

Maximum string length: 120
​
intermediary_swift_bic
string | null

Optional: the SWIFT/BIC of the intermediary bank.

Maximum string length: 11
​
purpose_of_payment
string | null

Optional: a short description of why the money is being sent (some corridors require it).

Maximum string length: 120
​
recipient_type
string | null

Optional: either "individual" or "business".

​
bank_branch
string | null

UniTeller branch / routing code (IFSC, SWIFT/BIC, or CLABE).

Maximum string length: 50
​
bank_document
string | null

Recipient bank document (e.g. CPF / CNPJ / RFC), where the corridor needs it.

Maximum string length: 100
​
payout_branch_id
integer | null

UniTeller numeric payout branch id used to route the payout.

Response

Successful Response

Standard response wrapper for single-object responses and errors.

Generic over the payload type. A route that declares CommonResponse[SomeModel] gets the real data schema rendered in OpenAPI/Swagger; a bare CommonResponse leaves data untyped.

​
status_code
integer
required

HTTP status code for the response.

​
data
any
required

Payload or error details.

​
query_generated_time
integer
required

UTC timestamp (milliseconds since epoch) when response was generated.