Recipients
Create, list, retrieve, 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.
Listing and reading recipients requires the banking:read scope; creating and editing them requires banking:write.
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. |
nickname |
— | Return recipients whose nickname matches exactly, ignoring case and surrounding spaces. |
pixKey |
— | Return PIX recipients whose saved PIX key matches exactly, ignoring case. Dots, dashes, and slashes in a CPF/CNPJ key are ignored, so 12.345.678/0001-99 and 12345678000199 match the same recipient. Phone keys must include the country code as saved, for example +5511999999999. |
Filters combine: a recipient must match all of them. The same PIX key can be saved for more than
one recipient, so pixKey can return several results. Nicknames are unique for new recipients, but
treat the result as a list either way.
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",
"nickname": "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. |
nickname |
Your saved display label, exactly as stored — the nickname you set at creation or by update, the recipient name when none was given at creation, or null when none is stored. |
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",
"nickname": "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. The list returns the recipients your dashboard shows: a Copia e Cola
code paid from the dashboard is a one-off payment and is not listed, although an older recipient
saved from one can still appear with pix.key: null.
Retrieve a recipient
GET /v1/banking/recipients/{recipientId}
x-api-key: dlfy_live_...
Returns 200 OK with { "recipient": ... } — the same recipient object as the list. Use it to check
that a recipient id you stored is still available before sending a transfer.
A recipient that was removed in the dashboard, one the dashboard does not list, or an id that
belongs to another organization, returns 404 recipient_not_found. Banking details can’t be edited in place: correcting them means
removing the recipient and creating a new one, which gets a new id. Editing the nickname or
receipt email keeps the same id.
Find a recipient you saved earlier
To reconcile your own records with Dolafy before a payout:
- Call
GET /v1/banking/recipients/{recipientId}with the id you stored. - On
404 recipient_not_found, search withGET /v1/banking/recipients?nickname=Fornecedor%20SP&pixKey=finance%40acme.example. - If a recipient comes back, store its
idand use it. If none does, create the recipient.
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 nickname (and 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",
"nickname": "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",
"nickname": "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.idis Dolafy’s identifier. Use it directly asrecipientIdwhen sending a transfer. nicknameis optional on every recipient type (PIX, ACH, and Wire). It only changes how the recipient is labeled for your team; verification always usesname(plusbusinessNameorfirstName/lastNamefor USD recipients). A nickname already used by another active external recipient returns409 recipient_nickname_already_exists.emailis 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
recipientobject has the same fields as list items, includingpix(PIX key and document) or maskedbankdetails, 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.documentNumberis the receiver’s tax id and must be a valid CPF fortype: "individual"or a valid CNPJ fortype: "business". Always send it: depending on your organization’s PIX payout route it is required, and a missing, invalid, or mismatched document then returns400 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, andaddress.postalCode.bank.accountTypedefaults tochecking.address.countrydefaults toUSAand otherwise uses a 3-letter ISO code; when supplied,address.statemust be a subdivision code such asNYorUS-NY. - When the configured banking route verifies recipients up front, the API does so before returning
201 Created. A verification rejection returns409 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 nickname and 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.