Recipients

Create, list, and update saved PIX, ACH, and Wire payout recipients.

A recipient is a saved bank payout destination. Reference its Dolafy id when you send a transfer. The list includes BRL PIX and API- or dashboard-created USD ACH/Wire recipients. Base USDC transfers submit a wallet address instead of a bank-recipient id, but that address must already be saved as an active Base USDC wallet recipient in the dashboard. Wallet recipients are not returned by this bank-recipient endpoint.

List recipients

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

Query parameters

Parameter	Default	Description
`limit`	`50`	Page size, capped at `100`.
`offset`	`0`	Number of records to skip.
`currency`	—	Filter by recipient currency, for example `BRL` or `USD`.
`rail`	—	Filter by payment rail: `pix`, `ach`, or `wire`.

List USD ACH recipients

USD ACH/Wire recipients created through the API or dashboard are available through this endpoint. For example:

GET /v1/banking/recipients?currency=USD&rail=ach
x-api-key: dlfy_live_...

{
  "recipients": [
    {
      "id": "b36b2c20-731b-4209-aacd-174a2ca39112",
      "name": "Acme US Vendor",
      "type": "us",
      "currency": "USD",
      "rails": ["ach", "wire"],
      "email": "finance@acme.example",
      "pix": null,
      "bank": {
        "name": "JPMorgan Chase",
        "routingNumber": "021000021",
        "accountNumberLast4": "6789",
        "accountType": "checking"
      },
      "createdAt": "2026-08-11T12:00:00.000Z",
      "updatedAt": "2026-08-11T12:00:00.000Z"
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "hasMore": false
  }
}

The rails array contains every transfer rail configured for the recipient, even when the list is filtered to one rail. Use the returned id as recipientId for a matching USD ACH or Wire transfer.

Recipient fields

Field	Description
`id`	Dolafy recipient id. Use it as `recipientId` when sending a transfer.
`name`	Display name of the recipient: the `nickname` you set at creation, or the recipient name when no nickname was set.
`type`	`pix` for BRL PIX recipients, `us` for USD bank recipients.
`currency`	`BRL` or `USD`.
`rails`	Every rail the recipient can receive on: `pix`, `ach`, `wire`.
`email`	The payment-receipt email you saved for this recipient, or `null`. It is your own metadata and is not shared with the receiving bank.
`pix`	PIX identification, or `null` for non-PIX recipients. `pix.key` is the saved PIX key (email, phone, CPF/CNPJ, or random key) and `pix.documentNumber` is the digits-only CPF/CNPJ, or `null` when not captured.
`bank`	USD bank identification, or `null` for PIX recipients. `bank.accountNumberLast4` is always the masked last four digits; `bank.accountType` is `checking` or `savings`.
`createdAt`, `updatedAt`	ISO 8601 timestamps.

BRL PIX response

{
  "recipients": [
    {
      "id": "9a5b47c1-234d-4841-a5b8-d1b790f774be",
      "name": "Acme Ltda",
      "type": "pix",
      "currency": "BRL",
      "rails": ["pix"],
      "email": "finance@acme.example",
      "pix": {
        "key": "finance@acme.example",
        "documentNumber": "12345678000199"
      },
      "bank": null,
      "createdAt": "2026-06-25T12:00:00.000Z",
      "updatedAt": "2026-06-25T12:00:00.000Z"
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "hasMore": false
  }
}

Provider recipient ids and full account numbers are never returned; USD account numbers are always masked to accountNumberLast4. A PIX recipient saved in the dashboard from a Copia e Cola code only can return pix.key: null.

Create a recipient

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

Recipient creation supports BRL PIX, USD ACH, and USD Wire. Banking details are create-only: after creation you can update the nickname and receipt email, but bank-verified fields cannot be edited and deletes are not part of v1. USD creation requires your organization’s matching ACH or Wire route to be active. Idempotency-Key is required — see Errors & Idempotency.

name is the recipient’s real name and is used for bank-side verification. The optional nickname (up to 120 characters) is your own display label — the same field as the dashboard’s “Account nickname”. It is shown in the dashboard recipient list, returned as the recipient name in API responses, and never shared with the receiving bank. When omitted, name is used as the label. The resulting nickname must be unique among your organization’s active external recipients, compared case-insensitively.

BRL PIX request

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

USD ACH request

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

{
  "name": "Acme US Vendor",
  "type": "business",
  "businessName": "Acme Vendor LLC",
  "email": "finance@acme.example",
  "currency": "USD",
  "rail": "ach",
  "bank": {
    "name": "JPMorgan Chase",
    "accountNumber": "000123456789",
    "routingNumber": "021000021",
    "accountType": "checking"
  },
  "address": {
    "streetLine1": "270 Park Avenue",
    "streetLine2": "Suite 1200",
    "city": "New York",
    "state": "NY",
    "postalCode": "10017",
    "country": "USA"
  }
}

Use "rail": "wire" and a new idempotency key to create a Wire recipient. Each request enables the returned recipient for one exact USD rail.

For an individual USD recipient, set "type": "individual" and include firstName and lastName instead of businessName:

{
  "name": "Ada Lovelace",
  "type": "individual",
  "firstName": "Ada",
  "lastName": "Lovelace",
  "currency": "USD",
  "rail": "wire",
  "bank": {
    "name": "JPMorgan Chase",
    "accountNumber": "000123456789",
    "routingNumber": "021000021",
    "accountType": "checking"
  },
  "address": {
    "streetLine1": "270 Park Avenue",
    "city": "New York",
    "state": "NY",
    "postalCode": "10017",
    "country": "USA"
  }
}

USD response

{
  "recipient": {
    "id": "b36b2c20-731b-4209-aacd-174a2ca39112",
    "name": "Acme US Vendor",
    "type": "us",
    "currency": "USD",
    "rails": ["ach"],
    "email": "finance@acme.example",
    "pix": null,
    "bank": {
      "name": "JPMorgan Chase",
      "routingNumber": "021000021",
      "accountNumberLast4": "6789",
      "accountType": "checking"
    },
    "createdAt": "2026-08-11T12:00:00.000Z",
    "updatedAt": "2026-08-11T12:00:00.000Z"
  },
  "idempotencyKey": "recipient-acme-ach-001"
}

BRL PIX response

{
  "recipient": {
    "id": "9a5b47c1-234d-4841-a5b8-d1b790f774be",
    "name": "Fornecedor SP",
    "type": "pix",
    "currency": "BRL",
    "rails": ["pix"],
    "email": "finance@acme.example",
    "pix": {
      "key": "finance@acme.example",
      "documentNumber": "12345678000199"
    },
    "bank": null,
    "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.
nickname is optional on every recipient type (PIX, ACH, and Wire). It only changes how the recipient is labeled for your team; verification always uses name (plus businessName or firstName/lastName for USD recipients). A nickname already used by another active external recipient returns 409 recipient_nickname_already_exists.
email is an optional payment-receipt email stored with the recipient. It is returned in recipient responses and can be changed later — see Update a recipient.
The recipient object has the same fields as list items, including pix (PIX key and document) or masked bank details, so you can confirm what was saved without a second call.
The same PIX key may be saved for different sellers. Each saved seller has its own recipient id and must use a distinct nickname.
pix.documentNumber is the receiver’s tax id and must be a valid CPF for type: "individual" or a valid CNPJ for type: "business". Always send it: depending on your organization’s PIX payout route it is required, and a missing, invalid, or mismatched document then returns 400 invalid_pix_document.
USD routing numbers must be valid 9-digit ABA routing numbers. Account numbers must contain 4–34 digits.
USD recipients require bank.name, bank.accountNumber, bank.routingNumber, address.streetLine1, address.city, and address.postalCode. bank.accountType defaults to checking. address.country defaults to USA and otherwise uses a 3-letter ISO code; when supplied, address.state must be a subdivision code such as NY or US-NY.
When the configured banking route verifies recipients up front, the API does so before returning 201 Created. A verification rejection returns 409 recipient_partner_sync_failed, and the incomplete local recipient is not left active. Other routes validate the PIX key and document at creation and re-check them on every transfer.
You can also create recipients from the dashboard; use a recipient only with a transfer rail it lists in rails.

Update a recipient

PATCH /v1/banking/recipients/:recipientId
x-api-key: dlfy_live_...
content-type: application/json

Updates the display-only fields of a saved recipient. Exactly two fields are editable, and at least one must be present:

Field	Description
`nickname`	Your display label, 1–120 characters. Shown in the dashboard and returned as the recipient `name`.
`email`	The payment-receipt email. Pass `null` to clear it.

{
  "nickname": "Fornecedor SP",
  "email": "receipts@acme.example"
}

Returns 200 OK with the same { "recipient": ... } shape as creation, reflecting the update. No Idempotency-Key is needed — the update is safe to retry.

Changing the nickname to one already used by another active external recipient returns 409 recipient_nickname_already_exists.

Bank-verified recipient details — name, businessName, firstName/lastName, bank, pix, and address — cannot be edited, because they were verified with the receiving bank when the recipient was created. Including any of them (or any other field) returns 400 invalid_body rather than being silently ignored. To correct banking details, remove the recipient in the dashboard and create a new one.

An unknown recipient id, or one that belongs to another organization or was removed, returns 404 recipient_not_found.