NATIO developer documentation

What NATIO is

NATIO is a payment orchestration technology layer. It sits between your platform and the licensed payment providers you work with: acquirers, banks, PSPs and local payment methods. Your systems speak one contract to NATIO; NATIO speaks each provider dialect, decides where every payment goes, retries safely when a provider fails, and reports what happened attempt by attempt.

Three boundaries define the platform and they shape the whole API:

• Funds move between the merchant and licensed providers. NATIO never holds funds. Balances and settlements in the API describe what providers hold and settle, not a NATIO account. GET /v1/balances returns custodian: false for exactly this reason.
• Card data never reaches NATIO. You send a payment method type, or a token reference issued by a PCI-compliant provider. Sensitive entry happens on provider-hosted pages. POST /v1/payment-methods rejects anything that looks like a card number.
• Every decision is recorded. Risk evaluation, routing, each provider attempt and each failover are written to the payment timeline, so support and finance can answer “why did this go there” without a provider ticket.

What the API does

One request creates a payment. Inside that request NATIO evaluates risk rules, resolves a routing decision into an ordered list of eligible provider accounts, calls the first one, and — if the failure is retryable — calls the next. The response carries the final status for synchronous rails, or processing with a next_action for rails that need the customer (redirect or QR).

curl https://api.natio.me/v1/payments \
  -H "Authorization: Bearer natio_sk_test_..." \
  -H "Idempotency-Key: order-1001" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "currency": "USD",
    "payment_method": "card",
    "country": "US",
    "reference": "ORD-1001"
  }'

The rest of the API is the same object read back in different shapes: the payment and its attempts, its timeline, its refunds, the ledger transactions it produced, the balances and settlements the providers report, and the webhook events that tell you about all of it without polling.

The object model

A payment is the unit you create; everything else hangs off it. The relationship that matters most is payment → attempts → transactions: one payment can have several attempts across several providers, but only the attempts that actually moved money produce transactions.

Payouts are the mirror image: they are created directly rather than derived from a payment, they are routed to a provider that supports the destination rail, and they produce their own transactions and settlement lines.

Base URLs and conventions

Production

https://api.natio.me — requires a live key (natio_sk_live_…), which is issued after KYB approval.

Local development

http://localhost:4000 — the server list in the API reference is read from the live OpenAPI document.

Versioning

Every resource lives under the /v1 prefix. Breaking changes ship as a new prefix, not as a change to an existing one.

Authentication

Authorization: Bearer natio_sk_test_… or natio_sk_live_…. The key determines merchant, project and mode.

Mode

A key is either test or live. Test keys reach the demo providers only; live keys never accept test_scenario.

Content type

application/json on every request with a body. Responses are JSON with a x-request-id header.

Amounts

Integers in the minor unit of the currency. 10000 with USD is 100.00 USD.

Idempotency

Send Idempotency-Key on every mutating request; replays return the stored response.

Pagination

Cursor based: limit (1–200, default 50) and cursor, with next_cursor and has_more on the list.

Spec

OpenAPI 3.1 document, rendered in the API reference.

Supported payment method types: card, bank_transfer, qr, open_banking, wallet, instant, local. Supported currencies: USD, EUR, GBP, CHF, PLN, CZK, SEK, NOK, DKK, AED, SGD, HKD, JPY, AUD, CAD, BRL, MXN, INR, IDR, VND, THB, PHP, MYR, TRY, ZAR, NGN, KES, SAR, KZT.

Where to start