Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.clevis.dev/llms.txt

Use this file to discover all available pages before exploring further.

The Payouts API pays a single beneficiary — typically an employee receiving the net_salary from a payroll calculation — through a stable, provider-agnostic interface.
In sandbox no real money is moved. Every payout in sandbox is handled by an in-process mock provider. There is no bank connectivity and no settlement. Do not point production payroll money at this surface.

​
What you can do

  • Create a payout for a beneficiary in MX, CO, AR, BR, CL, or PE
  • Retrieve, list, and cancel payouts
  • Discover per-country beneficiary requirements
  • Receive signed webhook callbacks on every status change

​
Mock markers — how to tell it is not real

Every response from /v1/payouts* in sandbox carries two unambiguous mock markers:
  • mock: true in the JSON body of every Payout resource
  • X-Clevis-Mock: true HTTP response header on every payout route
  • status_detail on mock-triggered terminal outcomes ends with "(mock trigger)."
  • GET /health includes a payouts block: { "enabled": true, "provider": "mock", "mode": "sandbox", "open_payouts": <int> }
If any of those markers is missing from a response, the request did not hit a v1 mock provider.

​
Decimal precision

All monetary amounts on the Payouts surface are JSON strings, just like the Payroll API. Parse them with your language’s Decimal type before doing any arithmetic. 
✅ correct:  {"amount": "1859928.00"}
❌ wrong:    {"amount": 1859928.00}  // could lose precision
You can pass amount in as either a number or a string — the API normalises to a 2-decimal string on the way back.

​
Supported countries

CountryPayout currencyDefault method
Mexico (MX)MXNBANK_TRANSFER
Colombia (CO)COPBANK_TRANSFER
Argentina (AR)ARSBANK_TRANSFER
Brazil (BR)BRLBANK_TRANSFER or PIX
Chile (CL)CLPBANK_TRANSFER
Peru (PE)PENBANK_TRANSFER
The currency you send must match the country’s payout currency, or you’ll get 400 PAYOUT_CURRENCY_MISMATCH. Per-country beneficiary field shapes (CLABE for MX, CBU/CUIL for AR, CPF for BR, RUT for CL, CCI for PE) are covered in Country requirements.

​
Status lifecycle

Every payout moves through this state machine: 
PENDING → PROCESSING → PAID            (happy path)
                   ↘
                     REJECTED          (provider/bank reject)
   ↘
     REJECTED                          (intake reject)
   ↘
     CANCELLED                         (caller cancels)
PAID, REJECTED, and CANCELLED are terminal. See Status lifecycle for full transition semantics and how the mock advances payouts.

​
Deterministic mock outcomes

Demos and tests need to be able to force any outcome without waiting on a timer or guessing. The mock exposes magic triggers — special external_id prefixes, amount suffixes, and request headers — that pick a deterministic plan at intake. See Magic triggers for the full list (including the MOCK_REJECT_BANK_ and MOCK_STUCK_ prefixes). These are dev/test affordances, not stable API behaviour. They will stay available while v1 is mock-backed; when the real dLocal provider ships, they remain only on the mock path.

​
Idempotency

Every create call is idempotent. Pass either an Idempotency-Key header or rely on external_id (which is automatically used as the idempotency key if the header is omitted). See Idempotency.

​
Real-time updates via webhooks

If you set notification_url on the create request, the provider POSTs a signed payout.status_changed event to that URL on every status transition. See Webhooks for the event shape and HMAC verification recipe.

​
Authentication

Every payout endpoint requires the same Bearer API key as the rest of the API: 
Authorization: Bearer YOUR_API_KEY
If PAYOUTS_ENABLED=false on the server, the routes return 403 PAYOUTS_DISABLED instead of being unmounted — so the error is explicit.

​
Next steps

Quickstart

Pay a payroll end to end in under five minutes.

Status lifecycle

Understand every transition the mock can make.

Country requirements

Beneficiary fields and check-digit rules per country.

Magic triggers

Force rejection, success, or stuck states on demand.