Developers

One integration, a sandbox that behaves like production, and no surprises.

NATIO is a REST API with predictable resources, integer amounts, idempotency on every mutating call and typed errors. The sandbox runs the full orchestration engine against demo providers, so routing, failover, timeouts and webhooks can all be exercised before a single live key exists.

Create a sandbox account Read the docs

First request

A payment in one call.

Authenticate with a secret key, send an amount in minor units, a currency and a payment method. The response carries the outcome, the route taken and every attempt behind it.

Keys

Secret keys are scoped to a project and a mode. Test keys reach demo providers; live keys reach the providers configured for your account and are issued after KYB approval. Keys are shown once and stored hashed.

natio_sk_test_ / natio_sk_live_

Idempotency

Required in practice on every create: a replayed key returns the original response, so a client retry can never duplicate a payment or a payout.

Idempotency-Key

Errors

Typed error codes with HTTP semantics: 401 unauthorized, 409 invalid_state_transition, 422 validation with a field path, 429 rate limited. Every response carries a request id for support.

code · message · request id

Pagination

List endpoints are cursor-paginated and filterable on the fields you actually search by: reference, status, provider, method, country, currency and date range.

cursor

Quickstart →Authentication →Errors & failure codes →

Request

curl -X POST 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",
    "test_scenario": "failover"
  }'

Surface

The endpoints you will actually use.

One namespace, versioned. The full specification is published as OpenAPI and rendered in the API reference.

Method	Path	Purpose
POST	/v1/payments	Create a payment; risk, routing and provider attempts run inside the request.
GET	/v1/payments/{id}/timeline	The ordered narrative of every decision made for that payment.
POST	/v1/payments/{id}/refund	Full or partial refunds, repeatable up to the captured amount.
POST	/v1/payouts	Send funds to a tokenised beneficiary through a licensed provider.
GET	/v1/transactions	Every money movement across providers, filterable and paginated.
GET	/v1/settlements	Settlement batches as reported by the providers.
POST	/v1/webhooks/test	Send a test event to your endpoints and inspect the delivery.
GET	/v1/test/scenarios	The sandbox scenarios available to force a provider outcome.

Full API reference →SDKs & clients →

Sandbox

Demo providers that fail the way real ones do.

Every test key runs against NATIO demo providers driven by the same adapter interface as a real integration. Pass a test_scenario to force the path you need to build for.

successfailovertimeouttimeout_recoveredunavailablehard_declinesoft_declineall_fail

Real orchestration

Risk evaluation, rule matching, provider selection, retries and webhooks all run in test mode. The only difference is which providers answer.

Failure paths on demand

Reproduce a fallback to a second provider, a timeout that turns out to have been charged, an outage or a total failure — deterministically, in a test suite.

Test and live are separate

Data, keys, webhook endpoints and provider accounts are isolated per mode. Switching mode in the dashboard changes what you see, never what exists.

Sandbox & test scenarios →

Webhooks

Signed events, retried, and logged.

Asynchronous outcomes arrive as events at your endpoints. Every delivery is signed, every attempt is recorded, and any delivery can be resent from the dashboard.

Signature: Natio-Signature carries a timestamp and an HMAC-SHA256 of timestamp.body computed with your endpoint secret. Verify both the digest and the freshness of the timestamp.
Events: payment.created, payment.processing, payment.authorized, payment.successful, payment.failed, payment.cancelled, payment.refunded, refund.successful, refund.failed, payout.created, payout.successful, payout.failed, settlement.created.
Retries: Non-2xx responses are retried with backoff — 30s, 2m, 10m, 30m, then 2h — up to the endpoint's attempt limit, after which the delivery is marked exhausted.
Observability: Request headers, response status, body excerpt and latency are stored per attempt and visible in the dashboard, with manual resend.
Testing: POST /v1/webhooks/test sends a synthetic event to your active endpoints so you can verify signatures before real traffic.

Webhook guide →

Delivery

POST /your/endpoint
Natio-Signature: t=1758531242,v1=9c1f...e07
Natio-Event-Id: evt_6Hd2...
Natio-Event-Type: payment.successful
Natio-Delivery-Attempt: 1

{
  "id": "evt_6Hd2...",
  "type": "payment.successful",
  "created_at": "2026-09-22T09:34:02.118Z",
  "data": { "object": "payment", "id": "pay_7Kq2...", "status": "successful" }
}

Documentation

Everything, in one place.

Guides for the paths you implement, a reference for the shapes you send, and an OpenAPI specification you can generate a client from.

Getting started

Guides

Reference

OpenAPI specification

The API is described by an OpenAPI document covering every endpoint, request body, response shape and error. Use it to generate a typed client in your own language, or to drive contract tests against the sandbox.

Open the reference

Start in the sandbox.

Register, create a test key, send your first payment and read its timeline. No live provider contract is needed to evaluate the platform.

Start Integration Talk to Us