Referencia de la API/Dispersiones

Dispersiones

Un lote de pagos preparado, revisado, aprobado y lanzado en conjunto, hasta 5.000 elementos, validado antes de mover dinero. Las filas pueden mezclar cuentas bancarias, teléfonos, emails y PagoMóvil. Tu política de aprobación define cuántas aprobaciones hacen falta y quién puede darlas; quien envía no puede aprobar. Los elementos se ejecutan uno a uno y cada intento se conserva. Un lote termina en completed o completed_with_failures, nunca en un éxito parcial silencioso.

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.

Parámetros

Idempotency-Keyheaderstringopcional

Campo	Tipo	obligatorio	Notas
name	string	opcional
items	array	obligatorio

Solicitud

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

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

Parámetros

idpathstringobligatorio

Get a disbursement with its review summary

GET/disbursements/{id}

Parámetros

idpathstringobligatorio

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

Parámetros

idpathstringobligatorio
item_idpathstringobligatorio

Campo	Tipo	obligatorio	Notas
recipient_id	string	opcional
recipient	InlineRecipient	opcional
channel	string	obligatorio
source_amount	Amount	obligatorio	Decimal string. Up to two decimals for fiat, six for USDC.
reference	string	opcional
memo	string	opcional

Submit for approval

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

Parámetros

idpathstringobligatorio

Approve a revision

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

The submitter cannot approve their own batch.

Parámetros

idpathstringobligatorio
revision_idpathstringobligatorio

Reject a revision

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

Parámetros

idpathstringobligatorio
revision_idpathstringobligatorio

Campo	Tipo	obligatorio	Notas
reason	string	opcional

Launch

POST/disbursements/{id}/launch

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

Parámetros

idpathstringobligatorio

Errores: 402 insufficient_balance; 409 approval_required

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

Parámetros

idpathstringobligatorio

Resume

POST/disbursements/{id}/resume

Parámetros

idpathstringobligatorio

Retry every retryable failed item

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

Parámetros

idpathstringobligatorio

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.

Parámetros

idpathstringobligatorio

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.