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

# Payouts Overview

> Pay an employee their net salary after a payroll calculation

The Payouts API pays a single beneficiary — typically an employee receiving the
`net_salary` from a [payroll calculation](/quickstart) — through a stable,
provider-agnostic interface.

<Warning>
  **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.
</Warning>

## 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> }`

## 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

| Country        | Payout currency | Default method           |
| -------------- | --------------- | ------------------------ |
| Mexico (MX)    | MXN             | `BANK_TRANSFER`          |
| Colombia (CO)  | COP             | `BANK_TRANSFER`          |
| Argentina (AR) | ARS             | `BANK_TRANSFER`          |
| Brazil (BR)    | BRL             | `BANK_TRANSFER` or `PIX` |
| Chile (CL)     | CLP             | `BANK_TRANSFER`          |
| Peru (PE)      | PEN             | `BANK_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](/payouts/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](/payouts/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](/payouts/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](/payouts/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](/payouts/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
```

## Next steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/payouts/quickstart">
    Pay a payroll end to end in under five minutes.
  </Card>

  <Card title="Status lifecycle" icon="diagram-project" href="/payouts/status-lifecycle">
    Understand every transition the mock can make.
  </Card>

  <Card title="Country requirements" icon="globe" href="/payouts/country-requirements">
    Beneficiary fields and check-digit rules per country.
  </Card>

  <Card title="Magic triggers" icon="wand-magic-sparkles" href="/payouts/magic-triggers">
    Force rejection, success, or stuck states on demand.
  </Card>
</CardGroup>