Référence API/Décaissements

Décaissements

Un lot de paiements préparé, revu, approuvé et lancé ensemble, jusqu’à 5 000 lignes, validé avant tout mouvement d’argent. Les lignes peuvent mêler comptes bancaires, numéros de téléphone, e-mails et PagoMóvil. Votre politique d’approbation fixe le nombre d’approbations et qui peut les donner ; le demandeur ne peut pas approuver. Les lignes s’exécutent une à une et chaque tentative est conservée. Un lot se termine en completed ou completed_with_failures, jamais en succès partiel silencieux.

Create a disbursement

POST/disbursements

A batch of payouts prepared, reviewed, approved and launched together. Up to 5,000 items. Rows are validated before any money moves.

Paramètres

Idempotency-Keyheaderstringfacultatif

Champ	Type	obligatoire	Notes
name	string	facultatif
items	array	obligatoire

Requête

{
  "name": "Agents, week 37",
  "items": [
    {
      "recipient_id": "rcp_9d1a",
      "channel": "spei_mxn",
      "source_amount": "2500.00",
      "reference": "AG-014"
    },
    {
      "recipient": {
        "type": "phone",
        "number": "+5215512345678"
      },
      "channel": "claim_link",
      "source_amount": "80.00",
      "reference": "driver-week-37"
    },
    {
      "recipient": {
        "type": "pagomovil",
        "phone_number": "+584141234567",
        "bank_code": "0102",
        "national_id": "V-12345678",
        "holder_name": "Ana Torres",
        "date_of_birth": "1990-04-12"
      },
      "channel": "pagomovil_ves",
      "source_amount": "150.00",
      "reference": "VE-22"
    }
  ]
}

Exemples: Create a disbursement

curl -X POST https://sandbox.api.decaf.so/v1/disbursements \
  -H "Authorization: Bearer $DECAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name":"Agents, week 37","items":[{"recipient_id":"rcp_9d1a","channel":"spei_mxn","source_amount":"2500.00","reference":"AG-014"},{"recipient":{"type":"phone","number":"+5215512345678"},"channel":"claim_link","source_amount":"80.00","reference":"driver-week-37"},{"recipient":{"type":"pagomovil","phone_number":"+584141234567","bank_code":"0102","national_id":"V-12345678","holder_name":"Ana Torres","date_of_birth":"1990-04-12"},"channel":"pagomovil_ves","source_amount":"150.00","reference":"VE-22"}]}'

Import items from CSV

POST/disbursements/{id}/items/import

Required columns `recipient`, `amount`. Optional `memo`, `reference`, `type`, `pagomovil_bank_code`, `pagomovil_national_id`, `pagomovil_holder_name`, `pagomovil_dob`.

Paramètres

idpathstringobligatoire

Get a disbursement with its review summary

GET/disbursements/{id}

Paramètres

idpathstringobligatoire

Réponse 200

{
  "id": "db_44e0",
  "name": "Agents, week 37",
  "status": "needs_review",
  "summary": {
    "item_count": 38,
    "ready": 36,
    "needs_review": 2,
    "total_source_amount": "96400.00",
    "total_fees": "412.10",
    "by_type": {
      "bank_account": 31,
      "phone": 5,
      "pagomovil": 2
    },
    "warnings": [
      {
        "code": "duplicate_recipient",
        "item_ids": [
          "di_18",
          "di_204"
        ]
      }
    ]
  },
  "balance_check": {
    "required": "96812.10",
    "available": "120000.00",
    "ok": true
  },
  "approval": {
    "required": 1,
    "received": 0,
    "revision_id": null
  }
}

Fix an item

PATCH/disbursements/{id}/items/{item_id}

Editable while drafting, and for failed items in correction mode. A change to a money-critical field creates a new execution version.

Paramètres

idpathstringobligatoire
item_idpathstringobligatoire

Champ	Type	obligatoire	Notes
recipient_id	string	facultatif
recipient	InlineRecipient	facultatif
channel	string	obligatoire
source_amount	Amount	obligatoire	Decimal string. Up to two decimals for fiat, six for USDC.
reference	string	facultatif
memo	string	facultatif

Submit for approval

POST/disbursements/{id}/submit-for-approval

Paramètres

idpathstringobligatoire

Approve a revision

POST/disbursements/{id}/approvals/{revision_id}/approve

The submitter cannot approve their own batch.

Paramètres

idpathstringobligatoire
revision_idpathstringobligatoire

Reject a revision

POST/disbursements/{id}/approvals/{revision_id}/reject

Paramètres

idpathstringobligatoire
revision_idpathstringobligatoire

Champ	Type	obligatoire	Notes
reason	string	facultatif

Launch

POST/disbursements/{id}/launch

Refused while items need review, approvals are outstanding, or the balance does not cover the batch.

Paramètres

idpathstringobligatoire

Erreurs: 402 insufficient_balance; 409 approval_required

Exemples: Launch

curl -X POST https://sandbox.api.decaf.so/v1/disbursements/db_44e0/launch \
  -H "Authorization: Bearer $DECAF_API_KEY"

Pause

POST/disbursements/{id}/pause

Paramètres

idpathstringobligatoire

Resume

POST/disbursements/{id}/resume

Paramètres

idpathstringobligatoire

Retry every retryable failed item

POST/disbursements/{id}/items/retry-failed

Paramètres

idpathstringobligatoire

Export results as CSV

GET/disbursements/{id}/export.csv

One row per item: reference, final status, amounts, fees, rate, provider reference, on-chain transaction, attempts, timestamps. Bank and ID fields masked.

Paramètres

idpathstringobligatoire

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.