Payouts

Sending money is its own module, on the same architecture.

Payouts are not payments in reverse. They have their own object, their own lifecycle and their own routing rules — but they run through the same provider adapters, the same idempotency guarantees and the same timeline and reconciliation as everything else on the platform.

Start Integration API reference

Create a payout

Amount, currency, and a tokenised destination.

Destinations are references, not account details. NATIO accepts a provider beneficiary token and a masked display value; requests carrying long digit sequences in the display field are rejected.

Three destination types

bank_account, wallet and card_token, each identified by a provider token plus a masked display value.

destination.type

No raw account numbers

NATIO stores the token, the masked display, the holder name and the country. Account numbers and card numbers stay with the provider that issued the token.

token

Idempotency

A retried request with the same key replays the original response. A network failure on your side cannot become a second payout.

Idempotency-Key

Cancel while pending

Payouts can be cancelled while created or pending. After submission to the provider the outcome is whatever the provider reports.

POST /v1/payouts/{id}/cancel

Request

curl -X POST https://api.natio.me/v1/payouts \
  -H "Authorization: Bearer natio_sk_test_..." \
  -H "Idempotency-Key: payout-2026-09-001" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 250000,
    "currency": "EUR",
    "destination": {
      "type": "bank_account",
      "token": "benef_tok_8f3a",
      "display": "IBAN ****4321",
      "holder_name": "Acme GmbH",
      "country": "DE"
    },
    "reference": "PAYOUT-2026-09-001"
  }'

Response · 201 Created

{
  "id": "po_4Bt8xC2nQ7hK",
  "object": "payout",
  "mode": "test",
  "status": "processing",
  "amount": 250000,
  "currency": "EUR",
  "destination": {
    "type": "bank_account",
    "display": "IBAN ****4321",
    "holder_name": "Acme GmbH",
    "country": "DE"
  },
  "route": {
    "provider_name": "NATIO Demo Bank",
    "provider_account_name": "Demo Bank · EUR",
    "rule": "EUR payouts → Demo Bank"
  },
  "failure": null,
  "created_at": "2026-09-22T09:14:02.118Z"
}

Lifecycle

Six states, one direction.

As with payments, transitions are validated and guarded; a provider notification that arrives twice cannot move a payout backwards.

Status	Meaning
created	Accepted and persisted. Routing has not produced a provider attempt yet.
pending	Waiting: a payout window, a provider queue or an internal approval. Cancellable.
processing	Submitted to the selected provider; the provider has not confirmed the credit.
successful	The provider confirmed the payout. Terminal.
failed	Rejected by the provider or no eligible provider remained. Carries a failure object. Terminal.
cancelled	Cancelled by the merchant while created or pending. Terminal.

Events: payout.created, payout.successful, payout.failed — delivered to your endpoints with the same signature scheme as payment events.

Routing

Payout routing is separate from payment routing.

Rules carry a transaction type. A rule written for payouts never affects a payment, and the provider that acquires your card traffic is rarely the one you use to pay beneficiaries.

Same conditions: Country, currency, merchant, project, amount, transaction type, risk score, hour of day and day of week, with the same operators as payment rules.
Same strategies: Ordered, weighted or score-based selection among the eligible provider accounts.
Eligibility: A provider account is a candidate only if it supports payouts, the currency and the destination country, and the amount is inside its configured limits.
Failover: Technical errors and provider unavailability cascade to the next eligible provider. As with payments, a timeout is verified with the provider before anything is retried.

How routing rules work →

Rule chain · payouts

01
IF transaction_type = payout AND currency = EUR → Provider A
02
IF currency = EUR AND amount > X → Provider B
03
IF Provider A unavailable → Provider C

Operations

The same records, on the sending side.

Payouts appear in the transaction monitor, in reconciliation and in settlement reporting alongside incoming volume, so finance sees one picture rather than two.

Timeline

Rule matched, provider selected, request sent, provider response, failover, terminal state — recorded per payout.

Transactions

Each payout writes a transaction with its provider reference, fee and currency, which reconciliation matches against provider reports.

Fees

The provider account's fee configuration is applied and stored with the payout, so outbound cost is comparable across providers.

No custody

NATIO instructs licensed providers; it does not hold, pool or disburse customer funds itself. The funding relationship stays between you and the provider.

Try payouts in the sandbox.

Demo providers reproduce success, hard decline, technical error, provider unavailable and timeout so you can build the failure paths before you go live.

Start Integration Talk to Us