Référence API/Bénéficiaires

Bénéficiaires

Un bénéficiaire est une destination enregistrée avec un seul type : compte bancaire, PagoMóvil, portefeuille, téléphone, e-mail ou utilisateur Decaf. Demandez à l’API les champs requis par chaque corridor plutôt que de les coder en dur : une CLABE à 18 chiffres au Mexique, une clé PIX et un CPF ou CNPJ au Brésil, un code SWIFT et une pièce d’identité à Hong Kong. Les champs bancaires et d’identité sont renvoyés masqués.

Required recipient fields for a channel

GET/channels/{channel}/requirements

Paramètres

channelpathstringobligatoire

Réponse 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"
  }
}

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

Paramètres

Idempotency-Keyheaderstringfacultatif

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

Requête

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

Réponse 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"
}

Erreurs: 422 recipient_not_ready

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

Paramètres

typequeryenum: bank_account, pagomovil, wallet, phone, email, decaf_userfacultatif
countryquerystringfacultatif
limitqueryintegerfacultatif
cursorquerystringfacultatif

Get a recipient

GET/recipients/{id}

Paramètres

idpathstringobligatoire

Update a recipient

PATCH/recipients/{id}

Paramètres

idpathstringobligatoire

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

Delete a recipient

DELETE/recipients/{id}

Paramètres

idpathstringobligatoire

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.

Paramètres

typequeryenum: phone, emailobligatoire
numberquerystringfacultatif
addressquerystringfacultatif

Réponse 200

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

Obtenir l’accès

Développez sur le sandbox dès cette semaine.

Dites-nous les corridors dont vous avez besoin et qui vous payez. Les clés sandbox sont délivrées par une personne.