Skip to main content

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 payoutNumber upon creation
  • Attachments: PDF documents can be attached. Required for USD and EUR transfers. Optional for ARS, BRL, and PYG.

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​

FieldTypeRequiredDescription
currencystringYesOne of ARS, BRL, PYG, USD, EUR
amountstringYesPositive decimal amount with up to two decimals. Example: "1000.50"
destinationJSON stringYesThe bank account that receives the funds. See Payout Destination
filesPDF file(s)ConditionalSupporting documents. Required for USD and EUR. See Attachments

Because the request is multipart/form-data, destination is 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.

FieldDescription
railPayment network used to reach the account. See Rails and currencies
countryCountry of the destination bank
accountIdentifierValueThe account identifier: PIX key, IBAN, CBU, alias, or local account number, depending on rail
labelOptional friendly name to find the destination later
institutionBank details (name, SWIFT/BIC, routing code, branch), when the rail requires them
beneficiaryOwner 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:

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​

CurrencyRailsAccount identifier
BRLBR_PIX, BR_TEDPIX key (CPF, CNPJ, email, phone, random key), or local account number
ARSAR_ACCOUNT_ID_TRANSFER, AR_LOCAL_TRANSFERCBU or alias, or local account number
PYGPY_ACCOUNT_ID_TRANSFER, PY_LOCAL_TRANSFERAlias (CI, RUC, phone, email), or local account number
USDINTERNATIONAL_WIREIBAN or local account number
EURSEPA_CREDIT_TRANSFERIBAN

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 USD and EUR transfers. Optional for ARS, BRL and PYG.

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:

StatusDescription
pendingTransfer created. Awaiting processing.
in_progressTransfer is being actively processed.
sanction_reviewTransfer is on hold while a compliance review is completed.
paidTransfer completed successfully. A receiptUrl may be available. Terminal state.
rejectedTransfer 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​

EventEffect on Balance
Transfer createdAmount is immediately deducted from the user's available balance
Transfer rejectedAmount 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_EXCEEDED error 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