Transfers
Send BRL PIX, USD ACH or Wire, and Base USDC transfers, then track their status to completion.
Send money to a saved bank recipient, or send USDC to a Base wallet recipient you saved in the dashboard. Every method is funded from your organization’s available balance.
Sending and cancelling transfers requires an API key with the banking:write scope; reading a transfer requires banking:read.
| Method | Required request fields | Destination amount precision |
|---|---|---|
| BRL PIX | currency: "BRL", rail: "pix", recipientId |
2 decimals |
| USD ACH | currency: "USD", rail: "ach", recipientId |
2 decimals |
| USD Wire | currency: "USD", rail: "wire", recipientId |
2 decimals |
| Base wallet | currency: "USDC", rail: "wallet", network: "base", destinationAddress |
Up to 6 decimals |
rail: "base" is also accepted as an input alias for rail: "wallet". Responses always return
rail: "wallet". Base is currently the only supported wallet network.
Wallet transfers require stablecoin access to be enabled for your organization. Save and activate
the Base USDC wallet recipient in the dashboard before calling the API; the submitted
destinationAddress must match that saved address. Lowercase and uppercase EVM addresses are
accepted. A mixed-case address must have a valid EIP-55 checksum.
Create a transfer
POST /v1/banking/transfers
x-api-key: dlfy_live_...
Idempotency-Key: transfer-acme-1048
content-type: application/json
Idempotency-Key is required. amount is the exact amount the bank recipient or wallet should
receive in the destination currency. The total USDC debit, including applicable fees, is calculated
automatically and is the amount checked against your organization’s send limit.
Bank transfer request
{
"recipientId": "9a5b47c1-234d-4841-a5b8-d1b790f774be",
"amount": "100.00",
"currency": "BRL",
"rail": "pix",
"memo": "Invoice 1048",
"description": "Acme Ltda supplier payout"
}
- ACH and Wire use an existing USD recipient created through the API or dashboard. Choose the same rail the recipient was configured for.
memois optional. When provided, it is sent as the transfer’s bank-facing reference on rails that carry one. Some PIX payout routes have no bank-facing reference; the memo is then stored on the transfer record and returned by the API, but the recipient’s bank statement will not show it.purposeCodeis optional. Include it when your configured ACH or Wire route requires one.descriptionis optional internal metadata and is not sent to the bank.
USD Wire example:
{
"recipientId": "b36b2c20-731b-4209-aacd-174a2ca39112",
"amount": "2500.00",
"currency": "USD",
"rail": "wire",
"memo": "INV-1048",
"description": "US supplier payout"
}
Wallet transfer request
Wallet transfers do not send a recipientId, but destinationAddress must match an active wallet
recipient saved in the dashboard:
{
"amount": "100.123456",
"currency": "USDC",
"rail": "wallet",
"network": "base",
"destinationAddress": "0x1111111111111111111111111111111111111111",
"description": "Treasury wallet payout"
}
Response
Returns 201 Created with the transfer wrapped in a transfer object:
{
"transfer": {
"id": "7b4f1f9c-7d92-4d12-a4aa-9c5b2f4f9b25",
"object": "banking.transfer",
"status": "pending",
"direction": "debit",
"rail": "pix",
"network": null,
"description": "Acme Ltda supplier payout",
"memo": "Invoice 1048",
"sourceCurrency": "USDC",
"sourceAmount": "18.82",
"destinationCurrency": "BRL",
"destinationAmount": "100.00",
"fxRate": "5.31349628",
"recipientId": "9a5b47c1-234d-4841-a5b8-d1b790f774be",
"destinationAddress": null,
"idempotencyKey": "transfer-acme-1048",
"createdAt": "2026-06-25T12:00:00.000Z",
"updatedAt": "2026-06-25T12:00:00.000Z",
"completedAt": null
}
}
sourceAmountis the total debited from your balance.fxRateis the all-in effective rate (destinationAmount / sourceAmount), inclusive of every charge applied to the transfer. The full USDC debit is alwaysdestinationAmount / fxRate.- For wallet transfers,
networkis"base",destinationAddressis the submitted address, andrecipientIdisnull. Bank transfers returnnetworkanddestinationAddressasnull. - If a wallet submission is rejected immediately after a provider transaction is created, the API
returns
201 Createdwithstatus: "failed". Replaying the same idempotency key returns that same failed transfer.
Rejected PIX recipients
A BRL PIX transfer to a recipient the payout network cannot pay fails with 422 and no transfer
object; no funds move. pix_recipient_bank_not_supported means the recipient’s PIX key belongs to
an unsupported bank, such as a credit cooperative (for example Sicoob): ask the seller for a PIX key
at a different bank, save it as a new recipient, and send with a new Idempotency-Key.
pix_payout_rejected carries the reason in error. Retrying the same recipient does not help.
Temporary funding failures
A burst of transfers from the same balance may temporarily exceed its funding capacity. When
creation returns a 503 error without a transfer object:
- Wait at least 60 seconds; use increasing delays with jitter for repeated failures.
- Retry the exact same request with the same
Idempotency-Key. - If the retry returns a
pendingorcompletedtransfer, track it normally. - If it returns a
failedorcancelledtransfer, the original attempt is closed. Submit a new payment with a new idempotency key only if you still want to send it.
Do not switch to a new key merely because the initial response is 503. See Errors &
Idempotency for the complete decision table.
Queue transfers
Send many payouts without spacing them out yourself. Add "queue": true to the create request, and
Dolafy accepts it immediately and sends your queued transfers one after another, in the order
received, as soon as your balance can fund the next one.
POST /v1/banking/transfers
x-api-key: dlfy_live_...
Idempotency-Key: payout-2026-10-13-0001
content-type: application/json
{
"recipientId": "9a5b47c1-234d-4841-a5b8-d1b790f774be",
"amount": "100.00",
"currency": "BRL",
"rail": "pix",
"memo": "Invoice 1048",
"queue": true
}
The response is 202 Accepted. The transfer has status: "queued", and sourceAmount and
fxRate are null because nothing has been priced yet:
{
"transfer": {
"id": "5c0e2f4a-1b7d-4f33-9a61-0f6a2d8c4e11",
"object": "banking.transfer",
"status": "queued",
"direction": "debit",
"rail": "pix",
"network": null,
"description": null,
"memo": "Invoice 1048",
"sourceCurrency": "USDC",
"sourceAmount": null,
"destinationCurrency": "BRL",
"destinationAmount": "100.00",
"fxRate": null,
"recipientId": "9a5b47c1-234d-4841-a5b8-d1b790f774be",
"destinationAddress": null,
"idempotencyKey": "payout-2026-10-13-0001",
"createdAt": "2026-10-13T12:00:00.000Z",
"updatedAt": "2026-10-13T12:00:00.000Z",
"completedAt": null
}
}
- Availability. Queueing is available for BRL PIX transfers. Other methods return
400 transfer_queue_not_supported. - Checked right away. The recipient, amount, route and transfer limits are checked before the request is accepted, so a bad request fails immediately and is never queued.
- Pricing. Each transfer is priced when it is sent, not when it was queued, so the final
sourceAmountandfxRatecan differ slightly from what you saw when you queued it. - The
idnever changes. Use it with Get a transfer and match it against webhooks. A queued transfer moves topending, then tocompleted(orfailed). - Failures. A transfer that fails before anything is sent ends
failed. It then carriesfailureCodeandfailureMessage, and you receive abanking.transfer.failedwebhook. Nothing was sent; submit it again with a newIdempotency-Keyif you still want to pay.failureCodeis one of:insufficient_balance;transfer_route_unavailable;pix_recipient_bank_not_supported,pix_payout_rejected,pix_quote_rejected;amount_out_of_range,recipient_not_available,banking_transfer_limit_exceeded;transfer_queue_expired;api_key_not_authorized(the key that queued it was revoked, expired or lostbanking:writebefore it was sent);transfer_failed.
- Expiry. A queued transfer that cannot be sent within 6 hours fails with
failureCodetransfer_queue_expired. - Retries. Retrying with the same
Idempotency-Keyreturns the same transfer. That holds with or withoutqueue, and a queued key is never sent twice. Sending the same key with a different amount or recipient returns409 banking_transfer_idempotency_conflict. - Balance. A queued transfer does not hold funds, so keep enough balance for everything you queue.
Cancel a queued transfer
POST /v1/banking/transfers/5c0e2f4a-1b7d-4f33-9a61-0f6a2d8c4e11/cancel
x-api-key: dlfy_live_...
This works only while the transfer is still queued and Dolafy has not yet tried to send it. It
returns the transfer with status: "cancelled" and sends a banking.transfer.cancelled webhook.
Once a send attempt has started, it returns 409 banking_transfer_not_cancellable. That stays true
even if the transfer is waiting to be retried.
Get a transfer
Poll a transfer, or reconcile after a missed webhook, using the id returned above.
GET /v1/banking/transfers/7b4f1f9c-7d92-4d12-a4aa-9c5b2f4f9b25
x-api-key: dlfy_live_...
Response
{
"transfer": {
"id": "7b4f1f9c-7d92-4d12-a4aa-9c5b2f4f9b25",
"object": "banking.transfer",
"status": "completed",
"direction": "debit",
"rail": "pix",
"network": null,
"description": "Acme Ltda supplier payout",
"memo": "Invoice 1048",
"sourceCurrency": "USDC",
"sourceAmount": "18.82",
"destinationCurrency": "BRL",
"destinationAmount": "100.00",
"fxRate": "5.31349628",
"recipientId": "9a5b47c1-234d-4841-a5b8-d1b790f774be",
"destinationAddress": null,
"idempotencyKey": "transfer-acme-1048",
"createdAt": "2026-06-25T12:00:00.000Z",
"updatedAt": "2026-06-25T12:01:20.000Z",
"completedAt": "2026-06-25T12:01:20.000Z"
}
}
Notes
statusis one ofpending,completed,failed, orcancelled, plusqueuedfor a queued transfer that has not been sent yet.- The object under
transferis exactly thedataobject delivered by banking webhooks — the same status-handling code works for both. - Only API-created transfers for your organization are returned. Unknown ids return
404 banking_transfer_not_found. - The response never includes provider ids, wallet ids, bank account details, or funding addresses.