API reference/Recipients

Recipients

A recipient is a saved destination with exactly one type: bank account, PagoMóvil, wallet, phone, email or Decaf user. Ask the API which fields a corridor needs instead of hard-coding them: an 18-digit CLABE in Mexico, a PIX key and CPF or CNPJ in Brazil, a SWIFT code and ID document in Hong Kong. Bank and ID fields are returned masked.

Required recipient fields for a channel

GET/channels/{channel}/requirements

Parameters

channelpathstringrequired

Response 200

{
  "channel": "spei_mxn",
  "recipient_type": "bank_account",
  "fields": [
    {
      "name": "holder_name",
      "type": "string",
      "required": true
    },
    {
      "name": "clabe",
      "type": "string",
      "required": true,
      "pattern": "^[0-9]{18}$"
    },
    {
      "name": "recipient_kind",
      "type": "enum",
      "values": [
        "individual",
        "business"
      ],
      "required": true
    }
  ],
  "limits": {
    "min": "30.12",
    "max": "300000.00",
    "currency": "USDC"
  }
}

Examples: Required recipient fields for a channel

curl -X GET https://sandbox.api.decaf.so/v1/channels/spei_mxn/requirements \
  -H "Authorization: Bearer $DECAF_API_KEY"

Create a recipient

POST/recipients

Parameters

Idempotency-Keyheaderstringoptional

Field	Type	required	Notes
type	RecipientType	required
country	string	optional
currency	string	optional
name	string	optional
kind	enum: individual, business	optional
external_id	string	optional
bank_account	object	optional	Fields from the channel requirements.
pagomovil	object	optional
wallet	object	optional
phone	object	optional
email	object	optional
decaf_user	object	optional

Request

{
  "type": "bank_account",
  "country": "HK",
  "currency": "HKD",
  "external_id": "vendor-4471",
  "name": "Brightway Electronics Ltd",
  "kind": "business",
  "bank_account": {
    "bank_name": "HSBC",
    "account_number": "123456789012",
    "swift": "HSBCHKHHHKH",
    "id_document_number": "12345678-000-01-23-4"
  }
}

Response 201

{
  "id": "rcp_9d1a",
  "type": "bank_account",
  "country": "HK",
  "currency": "HKD",
  "name": "Brightway Electronics Ltd",
  "kind": "business",
  "external_id": "vendor-4471",
  "status": "ready",
  "channels": [
    "chats_hkd"
  ],
  "bank_account": {
    "bank_name": "HSBC",
    "account_number": "•••• 9012",
    "swift": "HSBCHKHHHKH"
  },
  "created_at": "2026-09-16T14:59:00Z"
}

Errors: 422 recipient_not_ready

Examples: Create a recipient

curl -X POST https://sandbox.api.decaf.so/v1/recipients \
  -H "Authorization: Bearer $DECAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"type":"bank_account","country":"HK","currency":"HKD","external_id":"vendor-4471","name":"Brightway Electronics Ltd","kind":"business","bank_account":{"bank_name":"HSBC","account_number":"123456789012","swift":"HSBCHKHHHKH","id_document_number":"12345678-000-01-23-4"}}'

List recipients

GET/recipients

Parameters

typequeryenum: bank_account, pagomovil, wallet, phone, email, decaf_useroptional
countryquerystringoptional
limitqueryintegeroptional
cursorquerystringoptional

Get a recipient

GET/recipients/{id}

Parameters

idpathstringrequired

Update a recipient

PATCH/recipients/{id}

Parameters

idpathstringrequired

Field	Type	required	Notes
type	RecipientType	required
country	string	optional
currency	string	optional
name	string	optional
kind	enum: individual, business	optional
external_id	string	optional
bank_account	object	optional	Fields from the channel requirements.
pagomovil	object	optional
wallet	object	optional
phone	object	optional
email	object	optional
decaf_user	object	optional

Delete a recipient

DELETE/recipients/{id}

Parameters

idpathstringrequired

Check whether a phone or email can receive

GET/recipients/check

Says before sending whether a person in that country can receive, and by which methods.

Parameters

typequeryenum: phone, emailrequired
numberquerystringoptional
addressquerystringoptional

Response 200

{
  "receivable": true,
  "country": "MX",
  "methods": [
    "spei_bank",
    "decaf_wallet"
  ],
  "kyc_required_for": [
    "spei_bank"
  ]
}

Get access

Build against the sandbox this week.

Tell us the corridors you need and the recipients you pay. Sandbox keys are issued by a person.