Bank Transfers Overview
A bank transfer sends funds from the authenticated user's balance to a bank account in one of the supported fiat currencies. The destination can be a LATAM bank account (Argentina, Brazil, Paraguay), or a bank in the United States, Europe or Asia. The amount is deducted from the user's available balance at the time of creation.
Every bank transfer points to a payout destination: the saved bank details (and the beneficiary that owns them) that receive the funds. You can reference a destination you already created, or describe it inline and let the API create it for you.
- Endpoint:
POST /payout/transfer - Content type:
multipart/form-data - Supported currencies:
ARS,BRL,PYG,USD,EUR - Reference: Each transfer is assigned a unique
payoutNumberupon creation - Attachments: PDF documents can be attached. Required for
USDandEURtransfers. Optional forARS,BRL, andPYG.
API Reference: Create a bank transfer
Authentication
This endpoint requires a valid x-api-key and a Bearer Token issued to a store role in headers.
x-api-key: <your_api_key>
Authorization: Bearer <access_token>
Non store user requests will be rejected.
See the Authentication Guide to see more details.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
currency | string | Yes | One of ARS, BRL, PYG, USD, EUR |
amount | string | Yes | Positive decimal amount with up to two decimals. Example: "1000.50" |
destination | JSON string | Yes | The bank account that receives the funds. See Payout Destination |
files | PDF file(s) | Conditional | Supporting documents. Required for USD and EUR. See Attachments |
Because the request is
multipart/form-data,destinationis sent as a JSON-encoded string in a single form field.
Payout Destination
The destination object accepts one of two shapes. They are mutually exclusive: sending id together with the account fields is rejected.
Option A — Reuse a saved destination
Send the id of an existing, active payout destination.
{
"id": "123e4567-e89b-12d3-a456-426614174000"
}
Option B — Provide the bank details inline
Send the account details and the API finds the matching destination or creates it if it does not exist yet.
| Field | Description |
|---|---|
rail | Payment network used to reach the account. See Rails and currencies |
country | Country of the destination bank |
accountIdentifierValue | The account identifier: PIX key, IBAN, CBU, alias, or local account number, depending on rail |
label | Optional friendly name to find the destination later |
institution | Bank details (name, SWIFT/BIC, routing code, branch), when the rail requires them |
beneficiary | Owner of the account (name, type, tax ID, address), when the rail requires it |
The fields that are required change from rail to rail. Use Get the field requirements for payout destination rails to find out exactly what each rail needs before building your form.
{
"rail": "INTERNATIONAL_WIRE",
"country": "US",
"accountIdentifierValue": "1234567890",
"label": "Acme Corp - Bank of America",
"institution": {
"swiftBic": "BOFAUS3N",
"name": "Bank of America"
},
"beneficiary": {
"name": "Acme Corp",
"type": "juridico",
"taxId": "987654321",
"country": "US",
"address": "123 Main St, New York, NY 10001"
}
}
Managing destinations ahead of time
You can also create and look up destinations on their own, which is useful to keep a saved list of bank accounts for your users:
- Create a payout destination
- List payout destinations — supports searching by
labelor institution name - Get a payout destination by ID
- Edit a payout destination
Editing a destination never affects past transfers: each transfer keeps a snapshot of the destination as it was when the transfer was created.
Rails and currencies
| Currency | Rails | Account identifier |
|---|---|---|
BRL | BR_PIX, BR_TED | PIX key (CPF, CNPJ, email, phone, random key), or local account number |
ARS | AR_ACCOUNT_ID_TRANSFER, AR_LOCAL_TRANSFER | CBU or alias, or local account number |
PYG | PY_ACCOUNT_ID_TRANSFER, PY_LOCAL_TRANSFER | Alias (CI, RUC, phone, email), or local account number |
USD | INTERNATIONAL_WIRE | IBAN or local account number |
EUR | SEPA_CREDIT_TRANSFER | IBAN |
Each currency has its own step-by-step guide in this section.
Attachments
- Format: PDF only
- Maximum 10 files per transfer
- Maximum 1 MB per file
- Required for
USDandEURtransfers. Optional forARS,BRLandPYG.
Request Example
curl -X POST "/api/v1/payout/transfer" \
-H "x-api-key: <your_api_key>" \
-H "Authorization: Bearer <your_access_token>" \
-F "currency=USD" \
-F "amount=1000.50" \
-F 'destination={"rail":"INTERNATIONAL_WIRE","country":"US","accountIdentifierValue":"1234567890","label":"Acme Corp - Bank of America","institution":{"swiftBic":"BOFAUS3N","name":"Bank of America"},"beneficiary":{"name":"Acme Corp","type":"juridico","taxId":"987654321","country":"US","address":"123 Main St, New York, NY 10001"}}' \
-F "files=@invoice.pdf"
A successful request returns 201 Created with the created payout. It includes type set to transfer, the payoutNumber, and a snapshot of the destination used.
Transfer Lifecycle
Transfers progress through the following statuses, returned in the status field of the payout:
| Status | Description |
|---|---|
pending | Transfer created. Awaiting processing. |
in_progress | Transfer is being actively processed. |
sanction_review | Transfer is on hold while a compliance review is completed. |
paid | Transfer completed successfully. A receiptUrl may be available. Terminal state. |
rejected | Transfer rejected. Funds are restored. Terminal state. |
If the transfer is rejected by the payment provider, the metadata.payoutProvider.reason field explains why.
You can follow a transfer with Get payout by ID, or list your transfers with Get paginated list of payouts filtering by type=transfer.
Balance Impact
| Event | Effect on Balance |
|---|---|
| Transfer created | Amount is immediately deducted from the user's available balance |
| Transfer rejected | Amount is automatically restored to the user's balance |
Important Notes
- Accounts denominated in a currency other than USD can only send transfers in their own currency. USD accounts can send transfers in any supported currency
- Bank transfers count toward the store's daily payout limit, which is shared with crypto transfers. Check the remaining amount with Get the daily payout limit usage. Exceeding it returns the
PAYOUT_DAILY_LIMIT_EXCEEDEDerror code - A transfer with an amount higher than the available balance will result in an error
- Sending a currency your account is not allowed to operate returns
403 Forbidden