Skip to main content
POST
/
v1
/
payouts
Create a single payout (mock)
curl --request POST \
  --url https://api.example.com/v1/payouts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": 1,
  "currency": "<string>",
  "country": "<string>",
  "external_id": "<string>",
  "beneficiary": {
    "name": "<string>",
    "document_type": "<string>",
    "document_id": "<string>",
    "email": "<string>",
    "phone": "<string>",
    "address": {
      "country": "<string>",
      "state": "<string>",
      "city": "<string>",
      "zip_code": "<string>",
      "street": "<string>"
    },
    "bank_account": {}
  },
  "description": "<string>",
  "payment_method_id": "<string>",
  "payroll_ref": {
    "calculation_id": "<string>",
    "country": "<string>",
    "scheme": "<string>",
    "year": 2000,
    "concept": "<string>"
  },
  "notification_url": "<string>",
  "metadata": {},
  "processing": {
    "step_seconds": 30
  }
}
'

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.

Authorizations

​
Authorization
string
header
required

API key authentication. Send your API key as: Authorization: Bearer <your_api_key>

Headers

​
Idempotency-Key
string | null
​
X-Mock-Outcome
string | null
​
X-Mock-Outcome-At
string | null

Body

application/json

Request body for POST /v1/payouts.

​
amount
required

Positive decimal amount.

Required range: x > 0
​
currency
string
required

ISO 4217 code, uppercase.

Required string length: 3
​
country
string
required

ISO 3166-1 alpha-2.

Required string length: 2
​
external_id
string
required
Required string length: 1 - 80
​
beneficiary
Beneficiary · object
required

Beneficiary fields. Per-country shape is enforced by CreatePayoutRequest.

We keep bank_account typed as a generic dict here and do the per-country discrimination on the parent (where country is available). This avoids Pydantic's discriminator gotchas and produces cleaner error messages.

​
description
string | null
Maximum string length: 200
​
payment_method_id
string | null

Defaults to the country's default method if omitted.

​
payroll_ref
PayrollRef · object

Free traceability block linking a payout back to a payroll calculation.

Engine is stateless in v1, so calculation_id is informational only.

​
notification_url
string<uri> | null

HTTPS only. Receives signed webhook events on every status change.

Required string length: 1 - 2083
​
metadata
Metadata · object

≤20 keys, string values ≤500 chars.

​
processing
ProcessingOptions · object

Mock-only request knobs that control transition timing.

Response

Idempotent replay — existing payout returned.