NATIO
Orchestration

Every payment runs through the same engine. Every decision is written down.

The orchestration engine takes a payment from creation to a terminal state: it evaluates risk, selects providers by rule, sends the request, interprets the outcome, retries where it is safe to do so, and emits events. The whole sequence is stored as a timeline you can read from the API and the dashboard.

Start IntegrationTalk to Us
The engine

Four stages inside one request.

For synchronous payment methods the full sequence completes within the create request. For asynchronous methods the engine pauses at the provider's customer action and resumes when the provider notifies NATIO.

01

Risk evaluation

Configurable rules on amount, country, currency, method, IP, device, customer email, velocity and failed attempts produce a score and a decision: allow, review or block. Review holds the payment for an operator; block fails it with risk_blocked.
risk.evaluated
02

Routing

The first matching rule (merchant-specific before global, then by priority) selects candidate providers. Candidates are filtered for eligibility and ordered by the rule's strategy.
routing.evaluated
03

Provider attempt

The adapter for the selected provider account sends the request. Outcomes are normalised: success, requires_action, soft_decline, hard_decline, technical_error, timeout, provider_unavailable.
provider.request_sent
04

Retry, failover, events

Retryable outcomes cascade to the next candidate. Terminal outcomes update the state machine, write the transaction, and queue webhooks to your endpoints.
failover.initiated
Retry and failover

Retries only when it is safe. Never a second charge.

Whether NATIO retries depends on the failure category reported by the provider, and on what the provider says actually happened.

Double-charge protection
After a timeout NATIO looks the attempt up at the provider before doing anything else. If the provider confirms the charge, the payment is recovered as successful; only a confirmed absence of a charge allows a failover.
Unknown outcomes
If the provider cannot answer, the attempt is marked unknown and a status sync is scheduled. The payment does not fail over blind.
Attempts are recorded
Each attempt carries provider, account, outcome, provider code and message, fee and latency. They are returned on the payment object and shown in the dashboard.
Sandbox scenarios
test_scenario values such as failover, timeout, timeout_recovered, unavailable and all_fail reproduce each path against the demo providers.
Sandbox scenarios →
Failure categories
soft
Insufficient funds, do-not-honor, issuer unavailable, try again later, limits. May cascade to another eligible provider.
hard
Stolen, lost, expired or invalid card, fraud suspected, authentication failed, cancelled by customer. Never retried.
technical
Technical error, timeout, provider unavailable, configuration error. Fails over to the next provider after verification.
policy
No route available, unsupported currency or method, risk blocked, amount out of limits, attempts exhausted. Terminal.
State machine

Strict states, guarded transitions.

Payments, refunds and payouts move through explicit states. Transitions are validated in code and guarded at the database level, so concurrent writers cannot produce an invalid path.

StatusMeaningAllowed next states
createdAccepted and persisted; not yet sent to a provider.processing · pending · failed · cancelled
pendingWaiting: manual risk review, or a provider awaiting customer action.processing · failed · cancelled
processingA provider attempt is in flight, or the payment awaits an asynchronous confirmation.authorized · successful · failed · cancelled · pending
authorizedFunds reserved by the provider; capture pending (capture_method: manual).successful · cancelled · failed
capturedTransitional state during capture.successful
successfulThe provider confirmed the payment. Refundable.partially_refunded · refunded
partially_refundedOne or more refunds cover part of the captured amount.partially_refunded · refunded
refundedFully refunded. Terminal.—
failedDeclined, blocked or all eligible providers failed. Terminal, with a failure object.—
cancelledCancelled by the merchant before completion. Terminal.—

Refunds: created → processing → successful | failed. Payouts: created → pending → processing → successful | failed, cancellable while created or pending. An invalid transition returns 409 invalid_state_transition.

Transaction timeline

What a failover looks like from the outside.

The timeline is the human-readable record of the engine. This is the sequence produced by a card payment in the sandbox with test_scenario: failover, exactly as returned by GET /v1/payments/{id}/timeline.

  1. Payment created
    100.00 USD · card · US
    payment.created
  2. Risk evaluated: ALLOW
    score 0 · no rules matched
    risk.evaluated
  3. Routing rule evaluated: Cards → Acquirer A, fallback Acquirer B
    ordered strategy · 2 eligible provider(s)
    routing.evaluated
  4. NATIO Demo Acquirer A selected
    Attempt 1 · account Acquirer A · Test · fee 2.4% + 20
    provider.selected
  5. Request sent to provider
    NATIO Demo Acquirer A · createPayment
    provider.request_sent
  6. Provider technical error
    NATIO Demo Acquirer A · GW-500 Internal gateway error
    provider.error
  7. Fallback initiated
    technical error is retryable → next provider NATIO Demo Acquirer B
    failover.initiated
  8. NATIO Demo Acquirer B selected
    Attempt 2 · account Acquirer B · Test · fee 2.9% + 30
    provider.selected
  9. Request sent to provider
    NATIO Demo Acquirer B · createPayment
    provider.request_sent
  10. Payment successful
    NATIO Demo Acquirer B · 83 ms
    payment.successful
  11. Webhook queued for merchant
    1 endpoint(s) subscribed to payment.successful
    webhook.queued
Risk rules

A first line of defence, before routing.

The risk layer scores each payment with your rules before a provider is chosen. It is deliberately simple and transparent; it complements, rather than replaces, a dedicated fraud platform.

01

Signals

country, amount, currency, payment_method, ip, device_fingerprint, customer_email, velocity_1h, velocity_24h, failed_attempts_24h, amount_24h.
02

Decisions

Each matched rule adds to the score and proposes an action. The strongest action wins: allow, review or block. Decision id and score are returned in the payment's risk object.
03

Manual review

Payments under review wait in the dashboard. An operator's approve or reject is recorded on the timeline and in the audit log, then orchestration resumes or the payment fails.

See the engine on your own traffic.

Create a sandbox account, send payments with test scenarios and read the timeline for each of them.

Start IntegrationTalk to Us