Recipient Account

A Recipient Account represents the bank account or payout destination where funds will be delivered. Before creating a recipient account, you must first create the recipient as a participant and fetch the account schema for the destination country.

Schema-Driven Creation

Recipient account requirements vary by country. Always fetch the account schema before building your form or API call:

# Fetch account schema for Colombia
curl --request GET \
  --url https://{FQDN}/organizations/$TENANT/payout/recipientAccounts/schema/co \
  --header "x-api-key: $API_KEY" \
  --header "x-agent-id: $AGENT_ID" \
  --header "x-agent-api-key: $AGENT_KEY"

The schema returns a JSON Schema (draft-07) object that defines required fields, allowed values, and validation rules. Common fields include:

Field	Description	Examples
`asset`	Currency code (ISO 4217)	`BRL`, `MXN`, `COP`, `PEN`
`payoutMethod.type`	Payout mechanism	`BANK_DEPOSIT`
`payoutMethod.countryCode`	Destination country	`BR`, `MX`, `CO`
`payoutMethod.bankCode`	Bank identifier	Varies by country (use Banks endpoint)
`payoutMethod.routingNumber`	Routing/SWIFT/BIC code	Country-specific
`payoutMethod.accountNumber`	Account number	CLABE (MX), IBAN, or local account number
`payoutMethod.accountType`	Account type	`CHECKING`, `SAVINGS`

Tip: For countries that require a bankCode, use the Banks in a Country endpoint to populate a dropdown in your UI.

Creating a Recipient Account

Endpoint: POST /organizations/{tenant}/payout/participants/{participantId}/recipientAccounts/gateway
Authentication: Agent-level (x-api-key + x-agent-id + x-agent-api-key)

Request Body

Field	Type	Required	Description
`externalId`	string	No	Your internal identifier for this account
`asset`	string	Yes	Currency code (ISO 4217) for the recipient's account
`nickname`	string	No	Display name for the account
`payoutMethod`	object	Yes	Payout destination details (country-specific, see schema)
`payoutMethod.type`	string	Yes	`BANK_DEPOSIT`, `PIX`, `WALLET`, or `CARD` — availability depends on your corridor configuration

Fields by payout method type:

Type	Fields
`BANK_DEPOSIT`	`countryCode`, `bankCode`, `routingNumber`, `accountNumber`, `accountType` (`CHECKING`/`SAVINGS`)
`PIX` (Brazil)	`countryCode`, `keyType`, `key` (the PIX key)
`WALLET`	`countryCode`, `walletId`, `walletType`, `walletOperator`
`CARD`	`countryCode`, `cardTokenId` (tokenized card for push-to-card payout)

The account schema for each country is the source of truth for which types and fields your corridor supports.

Example: Colombia (Bank Deposit)

curl --request POST \
  --url https://{FQDN}/organizations/$TENANT/payout/participants/$RECIPIENT_ID/recipientAccounts/gateway \
  --header 'Content-Type: application/json' \
  --header "x-api-key: $API_KEY" \
  --header "x-agent-id: $AGENT_ID" \
  --header "x-agent-api-key: $AGENT_KEY" \
  --data '{
  "externalId": "acct-co-001",
  "asset": "COP",
  "payoutMethod": {
    "type": "BANK_DEPOSIT",
    "countryCode": "CO",
    "bankCode": "1001",
    "routingNumber": "1234",
    "accountNumber": "9876543210",
    "accountType": "SAVINGS"
  }
}'

Example: Mexico (CLABE)

curl --request POST \
  --url https://{FQDN}/organizations/$TENANT/payout/participants/$RECIPIENT_ID/recipientAccounts/gateway \
  --header 'Content-Type: application/json' \
  --header "x-api-key: $API_KEY" \
  --header "x-agent-id: $AGENT_ID" \
  --header "x-agent-api-key: $AGENT_KEY" \
  --data '{
  "externalId": "acct-mx-001",
  "asset": "MXN",
  "payoutMethod": {
    "type": "BANK_DEPOSIT",
    "countryCode": "MX",
    "bankCode": "002",
    "routingNumber": "002",
    "accountNumber": "012345678901234567",
    "accountType": "CHECKING"
  }
}'

Example: Peru (Bank Deposit)

curl --request POST \
  --url https://{FQDN}/organizations/$TENANT/payout/participants/$RECIPIENT_ID/recipientAccounts/gateway \
  --header 'Content-Type: application/json' \
  --header "x-api-key: $API_KEY" \
  --header "x-agent-id: $AGENT_ID" \
  --header "x-agent-api-key: $AGENT_KEY" \
  --data '{
  "externalId": "acct-pe-001",
  "asset": "PEN",
  "payoutMethod": {
    "type": "BANK_DEPOSIT",
    "countryCode": "PE",
    "bankCode": "BINPPEPL",
    "routingNumber": "1234",
    "accountNumber": "1345",
    "accountType": "CHECKING"
  }
}'

Save the returned id — this is the recipientAccountId required when creating a transaction.

Getting a Recipient Account

Endpoint: GET /organizations/{tenant}/payout/recipientAccounts/{recipientAccountId}
Authentication: Agent-level

curl --request GET \
  --url https://{FQDN}/organizations/$TENANT/payout/recipientAccounts/$ACCOUNT_ID \
  --header "x-api-key: $API_KEY" \
  --header "x-agent-id: $AGENT_ID" \
  --header "x-agent-api-key: $AGENT_KEY"

Sensitive fields (accountNumber, routingNumber, PIX key) are returned masked — the full values are never exposed after creation.

Deleting a Recipient Account

Endpoint: DELETE /organizations/{tenant}/payout/recipientAccounts/{recipientAccountId}
Authentication: Agent-level

curl --request DELETE \
  --url https://{FQDN}/organizations/$TENANT/payout/recipientAccounts/$ACCOUNT_ID \
  --header "x-api-key: $API_KEY" \
  --header "x-agent-id: $AGENT_ID" \
  --header "x-agent-api-key: $AGENT_KEY"

Returns 204 No Content.

Country-Specific Requirements

Country	Currency	Key Field	Document Type	Notes
Brazil (BR)	BRL	`accountNumber`	CPF	PIX keys may be supported depending on your corridor config
Mexico (MX)	MXN	`accountNumber` (CLABE, 18 digits)	CURP / INE	CLABE is the standard interbank identifier
Colombia (CO)	COP	`bankCode` + `accountNumber`	CC (Cédula)	Use the Banks endpoint for valid `bankCode` values
Peru (PE)	PEN	`bankCode` + `accountNumber`	DNI	Bank codes use SWIFT/BIC format
India (IN)	INR	`routingNumber` (IFSC)	PAN / Aadhaar	IFSC code is mandatory for Indian bank transfers
Philippines (PH)	PHP	`bankCode` + `accountNumber`	—	—

Always use the schema endpoint as the source of truth — the table above is for guidance only.

Integration Workflow

1. Fetch account schema  →  GET /payout/recipientAccounts/schema/{countryCode}
2. Fetch bank list        →  GET /payout/{countryCode}/banks (if bankCode is required)
3. Collect user input     →  Build form from schema
4. Create account         →  POST /payout/participants/{id}/recipientAccounts/gateway
5. Save account ID        →  Use in POST /fx/transactions

All Endpoints

Operation	Method	Endpoint
Create recipient account	`POST`	`/organizations/{tenant}/payout/participants/{participantId}/recipientAccounts/gateway`
Get recipient account	`GET`	`/organizations/{tenant}/payout/recipientAccounts/{recipientAccountId}`
Delete recipient account	`DELETE`	`/organizations/{tenant}/payout/recipientAccounts/{recipientAccountId}`