How the API Works

Every money-moving request follows the same pipeline, regardless of whether it is a payment, transfer, or exchange.

Request pipeline

flowchart LR
    A["Your Server"] -->|"POST /v1/payments"| B["OuiPay API"]
    B --> C["Record Attempt"]
    C --> D["Run Checks"]
    D --> E["Route to Provider"]
    E --> F["Post to Ledger"]
    F --> G["Fire Webhook"]
    G -->|"payment.completed"| A

    style C fill:#1e293b,color:#e2e8f0
    style D fill:#1e293b,color:#e2e8f0
    style E fill:#1e293b,color:#e2e8f0
    style F fill:#1e293b,color:#e2e8f0

Before any validation or provider call, the transaction is persisted with status pending. If the request is rejected later: validation, compliance, limits, provider outage: the entry still exists, marked failed with the exact reason. Nothing happens off the record.

Run checks

PIN step-up, feature flags, compliance screening, and limit checks run. A denial is a failed transaction with failure.code and failure.stage, not a silent rejection.

Route to provider

The engine picks a payment provider for the method/destination, places a hold on funds, and submits. A provider timeout leaves the transaction unknown : the outcome is never guessed.

Post to ledger

The double-entry ledger is the source of truth. Every status transition reflects a posted journal entry. Balances are always reconcilable to their journal entries.

Fire webhook

Signed webhooks fire for every status transition. You know the final state without polling: though GET /v1/transactions/{id} is always available.

Key principles

Principle	What it means
Attempt-first	The transaction entry exists before any processing
Explicit status	`pending`, `processing`, `completed`, `failed`, `unknown`: no guessing
Integer money	All amounts are integer minor units with ISO 4217 currency
Idempotent writes	`Idempotency-Key` makes retries safe; replays return the original
Signed webhooks	HMAC-SHA256 on every delivery; verify before acting
Append-only ledger	Corrections are compensating entries, never edits