Referencia de la API/Destinatarios

Destinatarios

Un destinatario es un destino guardado con un solo tipo: cuenta bancaria, PagoMóvil, billetera, teléfono, email o usuario Decaf. Pregunta a la API qué campos requiere cada corredor en lugar de codificarlos: una CLABE de 18 dígitos en México, una llave PIX y CPF o CNPJ en Brasil, un código SWIFT y documento de identidad en Hong Kong. Los campos bancarios y de identidad se devuelven enmascarados.

Required recipient fields for a channel

GET/channels/{channel}/requirements

Parámetros

channelpathstringobligatorio

Respuesta 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"
  }
}

Ejemplos: 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

Parámetros

Idempotency-Keyheaderstringopcional

Campo	Tipo	obligatorio	Notas
type	RecipientType	obligatorio
country	string	opcional
currency	string	opcional
name	string	opcional
kind	enum: individual, business	opcional
external_id	string	opcional
bank_account	object	opcional	Fields from the channel requirements.
pagomovil	object	opcional
wallet	object	opcional
phone	object	opcional
email	object	opcional
decaf_user	object	opcional

Solicitud

{
  "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"
  }
}

Respuesta 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"
}

Errores: 422 recipient_not_ready

Ejemplos: 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

Parámetros

typequeryenum: bank_account, pagomovil, wallet, phone, email, decaf_useropcional
countryquerystringopcional
limitqueryintegeropcional
cursorquerystringopcional

Get a recipient

GET/recipients/{id}

Parámetros

idpathstringobligatorio

Update a recipient

PATCH/recipients/{id}

Parámetros

idpathstringobligatorio

Campo	Tipo	obligatorio	Notas
type	RecipientType	obligatorio
country	string	opcional
currency	string	opcional
name	string	opcional
kind	enum: individual, business	opcional
external_id	string	opcional
bank_account	object	opcional	Fields from the channel requirements.
pagomovil	object	opcional
wallet	object	opcional
phone	object	opcional
email	object	opcional
decaf_user	object	opcional

Delete a recipient

DELETE/recipients/{id}

Parámetros

idpathstringobligatorio

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.

Parámetros

typequeryenum: phone, emailobligatorio
numberquerystringopcional
addressquerystringopcional

Respuesta 200

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

Obtén acceso

Construye contra el sandbox esta semana.

Cuéntanos los corredores que necesitas y a quién pagas. Las claves de sandbox las emite una persona.