API Reference

View as Markdown

Transfers

Create and fund payouts to a saved recipient, then track their status to completion.

Send money to a saved recipient. In v1, transfers are BRL PIX payouts funded from your organization’s available balance.

Create a transfer

POST /v1/banking/transfers
x-api-key: dlfy_live_...
Idempotency-Key: pix-acme-1048
content-type: application/json

Idempotency-Key is required. The recipient must already exist. amount is the amount the recipient should receive, in the destination currency (BRL). The funding source is debited automatically from your available balance.

Request

{
  "recipientId": "9a5b47c1-234d-4841-a5b8-d1b790f774be",
  "amount": "100.00",
  "currency": "BRL",
  "rail": "pix",
  "memo": "Invoice 1048",
  "description": "Acme Ltda supplier payout"
}
  • memo is optional. When provided, it is sent as the transfer’s bank-facing reference.
  • description is optional internal metadata and is not sent to the bank.

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",
    "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",
    "idempotencyKey": "pix-acme-1048",
    "createdAt": "2026-06-25T12:00:00.000Z",
    "updatedAt": "2026-06-25T12:00:00.000Z",
    "completedAt": null
  }
}
  • sourceAmount is the total debited from your balance.
  • fxRate is the all-in effective rate (destinationAmount / sourceAmount), inclusive of every charge applied to the transfer. The full USDC debit is always destinationAmount / fxRate.

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",
    "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",
    "idempotencyKey": "pix-acme-1048",
    "createdAt": "2026-06-25T12:00:00.000Z",
    "updatedAt": "2026-06-25T12:01:20.000Z",
    "completedAt": "2026-06-25T12:01:20.000Z"
  }
}

Notes

  • status is one of pending, completed, failed, or cancelled.
  • The object under transfer is exactly the data object 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.