Reference

API reference

One integration for payments, payouts, transactions and settlements across multiple providers. NATIO is a payment orchestration layer: funds move between the merchant and licensed payment providers. All amounts are integers in the currency's minor unit (e.g. 1000 = 10.00 USD).

Rendered from the live specification

This page is generated at request time from the OpenAPI 3.1.0 document served by the API — 23 operations across 9 tag groups. The raw document is at /openapi.json.

Servers

URL	Environment
`https://api.natio.me`	Production
`http://localhost:4000`	Local development

Authentication

Scheme	Type	How it is sent	Notes
`apiKey`	http · bearer	Authorization: Bearer <key>	API key: `sk_test_...` (sandbox) or `sk_live_...` (production)

Every operation requires apiKey unless it says otherwise. See Authentication for key modes, rotation and IP allow-lists.

Index

Payments

POST/v1/checkout-sessions

Create a hosted checkout session

Server-to-server only. Accepts an API or restricted redirect key. Requires an HTTPS return_url. Raw card details, saved tokens and crypto are not supported by this endpoint. Verify signed webhooks or API status after returning. A null url means no customer redirect is available.

Parameters

Name	In	Required	Type	Description
`Idempotency-Key`	header	optional	string(max length 255)	Unique key per logical request. Replays return the original response; reuse with a different body returns 422.

Request bodyrequired·CreatePaymentRequest

Field	Type	Notes
`traffic_type`	TrafficType
`amount`required	integer	Minor unitsmin 1
`currency`required	string	max length 3
`payment_method`required	PaymentMethodType \| object
`capture_method`	string	automatic · manual
`country`	string	max length 2
`customer`	CustomerInput
`description`	string	max length 500
`reference`	string	Your order idmax length 128
`return_url`	string <uri>
`metadata`	object
`test_scenario`	string	Sandbox only. See GET /v1/test/scenarios.
`device`	object
└`ip`	string
└`user_agent`	string
└`fingerprint`	string

Example request

{
  "amount": 10000,
  "currency": "USD",
  "payment_method": "card",
  "country": "US",
  "reference": "ORD-1001",
  "customer": {
    "external_id": "cust_42",
    "email": "buyer@example.com"
  },
  "test_scenario": "failover"
}

Responses

Status	Description	Body
201	Checkout created or idempotently replayed	—
403	Key scope, merchant eligibility or environment does not permit this request	—
422	Invalid checkout request	—

GET/v1/payments

List payments

Parameters

Name	In	Required	Type	Description
`status`	query	optional	string	Comma-separated statuses
`currency`	query	optional	string
`country`	query	optional	string
`payment_method`	query	optional	string
`reference`	query	optional	string
`search`	query	optional	string
`from`	query	optional	string <date-time>
`to`	query	optional	string <date-time>
`limit`	query	optional	integer(default 50 · min 1 · max 200)
`cursor`	query	optional	string	`next_cursor` from the previous page

Responses

Status	Description	Body
200	Paginated list	PaymentList

POST/v1/payments

Create a payment

Creates a payment and runs it through risk evaluation, routing and provider orchestration synchronously. The response contains the final status for synchronous methods, or processing with next_action for asynchronous methods (redirect, QR). Send an Idempotency-Key header to make retries safe.

Parameters

Name	In	Required	Type	Description
`Idempotency-Key`	header	optional	string(max length 255)	Unique key per logical request. Replays return the original response; reuse with a different body returns 422.

Request bodyrequired·CreatePaymentRequest

Field	Type	Notes
`traffic_type`	TrafficType
`amount`required	integer	Minor unitsmin 1
`currency`required	string	max length 3
`payment_method`required	PaymentMethodType \| object
`capture_method`	string	automatic · manual
`country`	string	max length 2
`customer`	CustomerInput
`description`	string	max length 500
`reference`	string	Your order idmax length 128
`return_url`	string <uri>
`metadata`	object
`test_scenario`	string	Sandbox only. See GET /v1/test/scenarios.
`device`	object
└`ip`	string
└`user_agent`	string
└`fingerprint`	string

Example request

{
  "amount": 10000,
  "currency": "USD",
  "payment_method": "card",
  "country": "US",
  "reference": "ORD-1001",
  "customer": {
    "external_id": "cust_42",
    "email": "buyer@example.com"
  },
  "test_scenario": "failover"
}

Responses

Status	Description	Body
201	Payment created and processed	Payment
401	Missing or invalid API key	Error
409	Invalid state transition or idempotency conflict	Error
422	Validation failed	Error
429	Too many requests	Error

GET/v1/payments/{id}

Retrieve a payment

Parameters

Name	In	Required	Type	Description
`id`	path	required	string

Responses

Status	Description	Body
200	Payment	Payment
404	Resource not found	Error

GET/v1/payments/{id}/timeline

Payment timeline

Ordered narrative of everything NATIO did for the payment: risk, routing, provider attempts, failover, webhooks.

Parameters

Name	In	Required	Type	Description
`id`	path	required	string

Responses

Status	Description	Body
200	Timeline	—

POST/v1/payments/{id}/capture

Capture an authorized payment

Parameters

Name	In	Required	Type	Description
`id`	path	required	string
`Idempotency-Key`	header	optional	string(max length 255)	Unique key per logical request. Replays return the original response; reuse with a different body returns 422.

Request body

Field	Type	Notes
`amount`	integer	Minor units; defaults to the full authorized amount

Responses

Status	Description	Body
200	Captured	Payment
409	Invalid state transition or idempotency conflict	Error

POST/v1/payments/{id}/cancel

Cancel a payment

Cancels a created, pending, authorized or customer-action payment. Payments that are being sent to a provider cannot be cancelled.

Parameters

Name	In	Required	Type	Description
`id`	path	required	string
`Idempotency-Key`	header	optional	string(max length 255)	Unique key per logical request. Replays return the original response; reuse with a different body returns 422.

Request body

Field	Type	Notes
`reason`	string

Responses

Status	Description	Body
200	Cancelled	Payment
409	Invalid state transition or idempotency conflict	Error

Refunds

POST/v1/payments/{id}/refund

Refund a payment

Parameters

Name	In	Required	Type	Description
`id`	path	required	string
`Idempotency-Key`	header	optional	string(max length 255)	Unique key per logical request. Replays return the original response; reuse with a different body returns 422.

Request body

Field	Type	Notes
`amount`	integer	Minor units; defaults to the remaining refundable amount
`reason`	string
`metadata`	object

Responses

Status	Description	Body
201	Refund	Refund
409	Invalid state transition or idempotency conflict	Error

GET/v1/payments/{id}/refunds

List refunds of a payment

Parameters

Name	In	Required	Type	Description
`id`	path	required	string

Responses

Status	Description	Body
200	Refunds	—

GET/v1/refunds/{id}

Retrieve a refund

Parameters

Name	In	Required	Type	Description
`id`	path	required	string

Responses

Status	Description	Body
200	Refund	Refund

Payouts

GET/v1/payouts

List payouts

Parameters

Name	In	Required	Type	Description
`status`	query	optional	string
`limit`	query	optional	integer(default 50 · min 1 · max 200)
`cursor`	query	optional	string	`next_cursor` from the previous page

Responses

Status	Description	Body
200	Payouts	—

POST/v1/payouts

Create a payout

Sends funds to a beneficiary through a licensed provider selected by the payout routing rules. Destinations are tokenised references; raw account numbers are never accepted.

Parameters

Name	In	Required	Type	Description
`Idempotency-Key`	header	optional	string(max length 255)	Unique key per logical request. Replays return the original response; reuse with a different body returns 422.

Request bodyrequired·CreatePayoutRequest

Field	Type	Notes
`amount`required	integer	min 1
`currency`required	string
`destination`required	object
└`type`required	string	bank_account · wallet · card_token
└`token`	string	Provider beneficiary token
└`display`required	string	Masked display value
└`holder_name`	string
└`country`	string
`description`	string
`reference`	string
`metadata`	object
`test_scenario`	string	success · technical_error · hard_decline · unavailable · timeout

Example request

{
  "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"
}

Responses

Status	Description	Body
201	Payout	Payout
422	Validation failed	Error

GET/v1/payouts/{id}

Retrieve a payout

Parameters

Name	In	Required	Type	Description
`id`	path	required	string

Responses

Status	Description	Body
200	Payout	Payout

POST/v1/payouts/{id}/cancel

Cancel a payout

Parameters

Name	In	Required	Type	Description
`id`	path	required	string

Responses

Status	Description	Body
200	Cancelled	Payout
409	Invalid state transition or idempotency conflict	Error

Transactions

GET/v1/transactions

List transactions

Ledger-style records of every financial movement (payments, refunds, payouts), including failed ones for monitoring.

Parameters

Name	In	Required	Type	Description
`type`	query	optional	string	payment · refund · payout · fee · adjustment
`status`	query	optional	string
`currency`	query	optional	string
`provider_account_id`	query	optional	string
`from`	query	optional	string <date-time>
`to`	query	optional	string <date-time>
`limit`	query	optional	integer(default 50 · min 1 · max 200)
`cursor`	query	optional	string	`next_cursor` from the previous page

Responses

Status	Description	Body
200	Transactions	—

Balances

GET/v1/balances

Processed and settled amounts per currency

NATIO is not a custodian. Figures are derived from processed transactions and settlement data reported by providers.

Responses

Status	Description	Body
200	Balances	—

Settlements

GET/v1/settlements

List provider settlements

Parameters

Name	In	Required	Type	Description
`status`	query	optional	string
`provider_account_id`	query	optional	string

Responses

Status	Description	Body
200	Settlements	—

GET/v1/settlements/{id}

Retrieve a settlement with its items

Parameters

Name	In	Required	Type	Description
`id`	path	required	string

Responses

Status	Description	Body
200	Settlement	Settlement

Payment methods

POST/v1/payment-methods

Store a tokenised payment method reference

Stores a reference to a token issued by a PCI-compliant provider. NATIO never accepts card numbers or CVV.

Request bodyrequired

Field	Type	Notes
`type`required	PaymentMethodType
`provider_token`required	string
`provider_code`	string
`customer`	CustomerInput
`display`	object

Responses

Status	Description	Body
201	Stored	PaymentMethod

GET/v1/payment-methods/{id}

Retrieve a payment method

Parameters

Name	In	Required	Type	Description
`id`	path	required	string

Responses

Status	Description	Body
200	Payment method	PaymentMethod

Webhooks

POST/v1/webhooks/test

Send a test event to your webhook endpoints

Request body

Field	Type	Notes
`event_type`	string	default "payment.successful"

Responses

Status	Description	Body
200	Queued	—

Sandbox

GET/v1/test/scenarios

List sandbox test scenarios

Responses

Status	Description	Body
200	Scenarios	—

GET/v1/me

Identify the API key's merchant, project and mode

Responses

Status	Description	Body
200	Identity	—

Schemas

The component schemas referenced above. Every $ref in the document points into this section.

Error

Field	Type	Notes
`error`	object
└`type`	string	invalid_request_error · authentication_error · permission_error · not_found_error · idempotency_error · rate_limit_error · state_error · provider_error · risk_error · internal_error
└`code`	string
└`message`	string
└`param`	string
└`details`	any
`request_id`	string

PaymentMethodType

string·card · bank_transfer · qr · open_banking · wallet · instant · local

TrafficType

Merchant-declared first or returning deposit cohort; never inferred from local history.

string·ftd · std · unknown

PaymentStatus

string·created · pending · processing · authorized · captured · successful · failed · cancelled · refunded · partially_refunded

CustomerInput

Field	Type	Notes
`id`	string
`external_id`	string
`email`	string <email>
`name`	string
`country`	string	max length 2

CreatePaymentRequest

Field	Type	Notes
`traffic_type`	TrafficType
`amount`required	integer	Minor unitsmin 1
`currency`required	string	max length 3
`payment_method`required	PaymentMethodType \| object
`capture_method`	string	automatic · manual
`country`	string	max length 2
`customer`	CustomerInput
`description`	string	max length 500
`reference`	string	Your order idmax length 128
`return_url`	string <uri>
`metadata`	object
`test_scenario`	string	Sandbox only. See GET /v1/test/scenarios.
`device`	object
└`ip`	string
└`user_agent`	string
└`fingerprint`	string

Payment

Field	Type	Notes
`id`	string
`traffic_type`	TrafficType
`object`	const "payment"
`mode`	string	test · live
`status`	PaymentStatus
`amount`	integer
`currency`	string
`captured_amount`	integer
`refunded_amount`	integer
`capture_method`	string
`payment_method`	object
└`type`	PaymentMethodType
└`id`	string \| null
`country`	string \| null
`description`	string \| null
`reference`	string \| null
`customer`	object \| null
`metadata`	object
`route`	object
└`provider`	object \| null
└`provider_account_id`	string \| null
└`provider_payment_id`	string \| null
└`attempts`	integer
└`routing_decision_id`	string \| null
└`rule`	string \| null
`risk`	object
└`decision_id`	string \| null
└`score`	integer \| null
`failure`	object \| null
└`code`	string
└`category`	string	soft · hard · technical · policy
└`message`	string
`next_action`	object \| null
└`type`	string	redirect · qr_code · display_details
└`url`	string
└`qrPayload`	string
└`expiresAt`	string
`fee`	object
└`amount`	integer
└`currency`	string
`processing_time_ms`	integer \| null
`attempts`	array of Attempt
`created_at`	string <date-time>
`updated_at`	string <date-time>
`processed_at`	string \| null <date-time>

PaymentList

Field	Type	Notes
`data`	array of Payment
`has_more`	boolean
`next_cursor`	string \| null

Attempt

Field	Type	Notes
`id`	string
`attempt_number`	integer
`status`	string	created · processing · unknown · authorized · succeeded · failed · cancelled
`outcome`	string \| null	success · requires_action · soft_decline · hard_decline · technical_error · timeout · provider_unavailable · unknown · null
`provider_id`	string
`provider_name`	string \| null
`provider_account_id`	string
`provider_payment_id`	string \| null
`provider_code`	string \| null
`provider_message`	string \| null
`failure`	object \| null
`fee_amount`	integer
`latency_ms`	integer \| null
`created_at`	string <date-time>

TimelineEvent

Field	Type	Notes
`id`	string
`type`	string
`title`	string
`description`	string \| null
`attempt_id`	string \| null
`data`	object
`created_at`	string <date-time>

Refund

Field	Type	Notes
`id`	string
`object`	const "refund"
`payment_id`	string
`amount`	integer
`currency`	string
`status`	string	created · processing · successful · failed
`reason`	string \| null
`provider_refund_id`	string \| null
`failure`	object \| null
`created_at`	string <date-time>

CreatePayoutRequest

Field	Type	Notes
`amount`required	integer	min 1
`currency`required	string
`destination`required	object
└`type`required	string	bank_account · wallet · card_token
└`token`	string	Provider beneficiary token
└`display`required	string	Masked display value
└`holder_name`	string
└`country`	string
`description`	string
`reference`	string
`metadata`	object
`test_scenario`	string	success · technical_error · hard_decline · unavailable · timeout

Payout

Field	Type	Notes
`id`	string
`object`	const "payout"
`mode`	string
`status`	string	created · pending · processing · successful · failed · cancelled
`amount`	integer
`currency`	string
`destination`	object
`route`	object
`fee`	object
`failure`	object \| null
`created_at`	string <date-time>

Transaction

Field	Type	Notes
`traffic_type`	TrafficType
`conversion`	object \| null	Routing and PSP outcome evidence. Technical uncertainty is null, not an approval decline. Synthetic evidence is explicitly labelled by source.
`id`	string
`type`	string
`status`	string
`entity_type`	string
`entity_id`	string
`payment_id`	string \| null
`amount`	integer	Signed; negative for refunds and payouts
`currency`	string
`fee_amount`	integer
`net_amount`	integer
`provider_name`	string \| null
`provider_reference`	string \| null
`payment_method`	string \| null
`country`	string \| null
`processing_time_ms`	integer \| null
`failure_code`	string \| null
`settlement_id`	string \| null
`occurred_at`	string <date-time>

Balance

Field	Type	Notes
`currency`	string
`processed_gross`	integer
`fees`	integer
`processed_net`	integer
`settled_by_providers`	integer
`awaiting_provider_settlement`	integer
`payouts_sent`	integer
`note`	string

Settlement

Field	Type	Notes
`id`	string
`provider_name`	string \| null
`settlement_entity`	string \| null
`settlement_reference`	string \| null
`currency`	string
`gross_amount`	integer
`fee_amount`	integer
`net_amount`	integer
`transaction_count`	integer
`period_start`	string <date-time>
`period_end`	string <date-time>
`status`	string	pending · settled · failed
`settled_at`	string \| null <date-time>
`items`	array of object

PaymentMethod

Field	Type	Notes
`id`	string
`object`	const "payment_method"
`type`	PaymentMethodType
`customer_id`	string \| null
`display`	object
`status`	string
`created_at`	string <date-time>

WebhookEvent

Field	Type	Notes
`id`	string
`type`	string
`mode`	string	test · live
`created_at`	string <date-time>
`data`	object
└`object`	object	The payment, refund, payout or settlement object