Referência da API/Dispersões

Dispersões

Um lote de pagamentos preparado, revisado, aprovado e lançado em conjunto, até 5.000 itens, validado antes de qualquer movimentação. As linhas podem misturar contas bancárias, telefones, e-mails e PagoMóvil. Sua política de aprovação define quantas aprovações são necessárias e quem pode dá-las; quem submete não aprova. Os itens executam um a um e cada tentativa é guardada. Um lote termina em completed ou completed_with_failures, nunca em sucesso 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	obrigatório	Observações
name	string	opcional
items	array	obrigatório

Requisição

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

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

idpathstringobrigatório

Get a disbursement with its review summary

GET/disbursements/{id}

Parâmetros

idpathstringobrigatório

Resposta 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

idpathstringobrigatório
item_idpathstringobrigatório

Campo	Tipo	obrigatório	Observações
recipient_id	string	opcional
recipient	InlineRecipient	opcional
channel	string	obrigatório
source_amount	Amount	obrigatório	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

idpathstringobrigatório

Approve a revision

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

The submitter cannot approve their own batch.

Parâmetros

idpathstringobrigatório
revision_idpathstringobrigatório

Reject a revision

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

Parâmetros

idpathstringobrigatório
revision_idpathstringobrigatório

Campo	Tipo	obrigatório	Observações
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

idpathstringobrigatório

Erros: 402 insufficient_balance; 409 approval_required

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

idpathstringobrigatório

Resume

POST/disbursements/{id}/resume

Parâmetros

idpathstringobrigatório

Retry every retryable failed item

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

Parâmetros

idpathstringobrigatório

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

idpathstringobrigatório

Obtenha acesso

Construa contra o sandbox esta semana.

Conte-nos os corredores de que precisa e quem você paga. As chaves de sandbox são emitidas por uma pessoa.