Recipients

List and create saved payout recipients. Transfers are sent to a saved recipient id.

A recipient is a saved payout destination. You create a recipient once, then reference its Dolafy id when you send a transfer. In v1, recipients are BRL PIX destinations.

List recipients

GET /v1/banking/recipients
x-api-key: dlfy_live_...

Query parameters

Response

{
  "recipients": [
    {
      "id": "9a5b47c1-234d-4841-a5b8-d1b790f774be",
      "name": "Acme Ltda",
      "type": "pix",
      "currency": "BRL",
      "rails": ["pix"],
      "createdAt": "2026-06-25T12:00:00.000Z",
      "updatedAt": "2026-06-25T12:00:00.000Z"
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "hasMore": false
  }
}

Provider recipient ids, account numbers, and PIX keys are never returned.

Create a recipient

POST /v1/banking/recipients
x-api-key: dlfy_live_...
Idempotency-Key: recipient-acme-pix-001
content-type: application/json

Current scope: BRL PIX only (currency: "BRL", rail: "pix"), create-only. Idempotency-Key is required — see Errors & Idempotency.

Request

{
  "name": "Acme Ltda",
  "type": "business",
  "currency": "BRL",
  "rail": "pix",
  "pix": {
    "key": "finance@acme.example",
    "documentNumber": "12345678000199"
  },
  "email": "finance@acme.example"
}

Response

{
  "recipient": {
    "id": "9a5b47c1-234d-4841-a5b8-d1b790f774be",
    "name": "Acme Ltda",
    "type": "pix",
    "currency": "BRL",
    "rails": ["pix"],
    "createdAt": "2026-06-25T12:00:00.000Z",
    "updatedAt": "2026-06-25T12:00:00.000Z"
  },
  "idempotencyKey": "recipient-acme-pix-001"
}

Notes

• The returned recipient.id is Dolafy’s identifier. Use it directly as recipientId when sending a transfer.
• Creating a recipient with a PIX key that already exists returns 409 recipient_already_exists, unless you are replaying the same idempotency key.
• You can also create recipients from the dashboard; API transfers can pay any saved recipient regardless of where it was created.