# Transfers

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

Send money to a saved [recipient](/docs/banking-recipients). In v1, transfers are **BRL PIX** payouts funded from your organization's available balance.

## Create a transfer

```http
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

```json
{
  "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:

```json
{
  "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.

```http
GET /v1/banking/transfers/7b4f1f9c-7d92-4d12-a4aa-9c5b2f4f9b25
x-api-key: dlfy_live_...
```

### Response

```json
{
  "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](/docs/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.