API reference/Disbursements

Disbursements

A batch of payouts prepared, reviewed, approved and launched together, up to 5,000 items, validated before any money moves. Rows can mix bank accounts, phone numbers, emails and PagoMóvil. Your approval policy sets how many approvals are needed and who may give them; the submitter cannot approve. Items execute one at a time and every attempt is kept. A batch ends completed or completed_with_failures, never a silent partial success.

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.

Parameters

Idempotency-Keyheaderstringoptional

Field	Type	required	Notes
name	string	optional
items	array	required

Request

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

Examples: 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`.

Parameters

idpathstringrequired

Get a disbursement with its review summary

GET/disbursements/{id}

Parameters

idpathstringrequired

Response 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.

Parameters

idpathstringrequired
item_idpathstringrequired

Field	Type	required	Notes
recipient_id	string	optional
recipient	InlineRecipient	optional
channel	string	required
source_amount	Amount	required	Decimal string. Up to two decimals for fiat, six for USDC.
reference	string	optional
memo	string	optional

Submit for approval

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

Parameters

idpathstringrequired

Approve a revision

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

The submitter cannot approve their own batch.

Parameters

idpathstringrequired
revision_idpathstringrequired

Reject a revision

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

Parameters

idpathstringrequired
revision_idpathstringrequired

Field	Type	required	Notes
reason	string	optional

Launch

POST/disbursements/{id}/launch

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

Parameters

idpathstringrequired

Errors: 402 insufficient_balance; 409 approval_required

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

Parameters

idpathstringrequired

Resume

POST/disbursements/{id}/resume

Parameters

idpathstringrequired

Retry every retryable failed item

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

Parameters

idpathstringrequired

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.

Parameters

idpathstringrequired

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.