CleonPay
Sign up
Solutions PaymentsPayoutsMethodsDocs Sign in Sign up

API: Payouts

Send money to an individual, to a card or a bank account.

A payout goes to a recipient, so a recipient is created first. That separation is deliberate: recipient details are sealed at rest and reused, and the payout request itself carries no personal data.

On this page

POST Create a recipient /v1/payout-recipients POST Send a payout /v1/payouts GET Retrieve a payout /v1/payouts/{id} GET List payouts /v1/payouts GET Available payout rails /v1/payout-methods

Create a recipient

POST /v1/payout-recipients

Stores who is being paid. A card recipient is created from the card number, its expiry, and the recipient’s date of birth and address (the scheme requires them for a card payout).

Send an Idempotency-Key header. Retrying with the same key returns the original result rather than creating a second one. See idempotency.

Body parameters

FieldTypeDescription
type
required		 string card or bank_account.
first_name
required		 string As held by the bank.
last_name
required		 string As held by the bank.
card_number string Card recipients (required): the card, 12–19 digits. Encrypted at rest; send with the expiry.
expiry_month string MM, with card_number.
expiry_year string YYYY, with card_number.
date_of_birth string Card recipients (required): YYYY-MM-DD.
iban string Bank recipients: the account, in IBAN form (SEPA).
bic string Bank recipients: required outside SEPA reach.
sort_code string Bank recipients: six digits, UK Faster Payments.
account_number string Bank recipients: eight digits, UK Faster Payments.
address_line1 string Street address. Required by card and SEPA rails.
city string Required by card and SEPA rails.
postal_code string Required by card and SEPA rails.
last4 string Last four digits, for your own reporting only.
scheme string visa, mastercard or amex.
country string Two-letter ISO 3166 code.
email string Optional, used by some rails for notification.
date_of_birth string YYYY-MM-DD. Required by some rails for sanctions screening.
reference string Your own identifier for this recipient.

Request

curl https://api.cleonpay.com/v1/payout-recipients \
  -H "Authorization: Bearer ck_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "card",
    "first_name": "Sofia",
    "last_name": "Almeida",
    "country": "PT",
    "card_number": "5555555555554444",
    "expiry_month": "11",
    "expiry_year": "2031",
    "date_of_birth": "1992-04-07",
    "address_line1": "Rua das Flores 12",
    "city": "Lisboa",
    "postal_code": "1100-001",
    "reference": "order-1001"
  }'

Response

{
  "id": "6d4ff39f-72fb-44c4-9e13-9c724683d40a",
  "object": "payout_recipient",
  "type": "card",
  "scheme": "mastercard",
  "last4": "4444",
  "created_at": "2026-08-21T15: 02: 19.441Z"
}

A card payout needs the card_number with its expiry, plus the recipient’s date_of_birth and address — the scheme requires them. Vendor tokens and paying back to an earlier payment are not available for card payouts today.

Send a payout

POST /v1/payouts

Sends money to a recipient over the rail you choose.

Send an Idempotency-Key header. Retrying with the same key returns the original result rather than creating a second one. See idempotency.

Body parameters

FieldTypeDescription
recipient_id
required		 string From the call above.
method
required		 string A rail from GET /v1/payout-methods, for example card_payout or sepa_credit_transfer.
amount
required		 integer Minor units.
currency
required		 string Three-letter ISO 4217 code.
reference string Your own identifier. Shown on the recipient statement where the rail carries it.
metadata object Stored and returned unchanged. With named balance accounts enabled, metadata.balance_account selects the account the payout (and its fee) draws from; unset or main is your default balance. An account that is not funded in the key’s environment is refused with balance_account_not_found.

Request

curl https://api.cleonpay.com/v1/payouts \
  -H "Authorization: Bearer ck_live_..." \
  -H "Idempotency-Key: payout-2026-0001" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_id": "6d4ff39f-72fb-44c4-9e13-9c724683d40a",
    "method": "card_payout",
    "amount": 2500,
    "currency": "EUR",
    "reference": "PAYOUT-2026-0001"
  }'

Response

{
  "id": "9a2c1e77-3b41-4e0a-9f18-0c5b2d7e6a33",
  "object": "payout",
  "status": "sent",
  "amount": 2500,
  "currency": "EUR",
  "method": "card_payout",
  "recipient_id": "6d4ff39f-72fb-44c4-9e13-9c724683d40a",
  "reference": "PAYOUT-2026-0001",
  "failure": null,
  "returned": null,
  "livemode": true,
  "created_at": "2026-08-21T15: 04: 52.118Z",
  "completed_at": null
}

Retrieve a payout

GET /v1/payouts/{id}

Returns one payout. A returned payout carries a returned object with the reason the receiving bank gave.

Response

{
  "id": "9a2c1e77-3b41-4e0a-9f18-0c5b2d7e6a33",
  "object": "payout",
  "status": "returned",
  "returned": {
    "code": "account_closed",
    "reason": "Beneficiary account closed"
  },
  "completed_at": "2026-08-24T07: 31: 09.660Z"
}

returned is not failed. Failed means the money never left. Returned means it reached the recipient's bank and came back, sometimes days later, and your balance moved in between.

List payouts

GET /v1/payouts

Every payout on the account, newest first.

Query parameters

FieldTypeDescription
limit integer Between 1 and 100. Defaults to 25.
status string Filter to one status.

Response

{
  "object": "list",
  "data": [ { "id": "9a2c1e77-...", "object": "payout", "status": "completed" } ]
}

Available payout rails

GET /v1/payout-methods

The rails enabled on your account, with what each one reaches and how quickly.

Response

{
  "object": "list",
  "data": [
    {
      "method": "card_payout",
      "display_name": "Card payout",
      "recipient_type": "card",
      "typical_speed": "Instant",
      "can_be_returned": false
    }
  ]
}

On every request

HeaderDescription
Authorization Bearer <api key>. The key decides whether you are in sandbox or live; the host is the same either way.
Content-Type application/json on every request with a body.
Idempotency-Key On every creating request. Up to 255 characters, unique per operation, valid for 24 hours.

Errors follow one shape across every endpoint, described in errors.

PreviousAPI: Refunds NextAPI: Balance