Oxagile Payment Gateway

Sessions

Auth · Bearer api key

Method	Path	Description
POST	`/api/v1/sessions`	Create a checkout session; pins amount, currency, region (→ processor) and methods. Returns a one-time `client_secret`.

Client checkout

Auth · X-Client-Key + origin

Method	Path	Description
POST	`/api/v1/client/pay`	Pay against a session with a processor token. Honors an optional `Idempotency-Key` header. Returns the transaction (captured / pending / declined).
POST	`/api/v1/client/checkout`	Hosted-checkout card submission (used by the `@oxagile/checkout` SDK): vaults the PAN (KMS-encrypted CDE) and charges the token. Returns `{transaction_id, status, masked_pan, …}` — never the PAN.

Transactions

Auth · Bearer api key

Method	Path	Description
GET	`/api/v1/transactions/{id}`	Fetch a transaction.
POST	`/api/v1/transactions/{id}/capture`	Capture an authorized transaction.
POST	`/api/v1/transactions/{id}/settle`	Mark a captured transaction settled (clearing complete).
POST	`/api/v1/transactions/{id}/void`	Void an authorized transaction.
POST	`/api/v1/transactions/{id}/refund`	Refund. No body → full remaining; `{amount, currency}` → partial. Supports multiple partial refunds.

Wallet & top-ups

Auth · Bearer api key or X-Client-Key

Method	Path	Description
GET	`/api/v1/wallet/{customer}`	Stored-value balance + ledger for a customer.
POST	`/api/v1/wallet/topup`	Top up: a geo-routed card payment that credits the balance on capture.
POST	`/api/v1/wallet/{customer}/spend`	Spend from balance (in-app purchase) — no processor round-trip.
POST	`/api/v1/wallet/{customer}/payout`	Withdraw to an external destination via the regional acquirer.

Buyer-facing equivalents under /api/v1/client/wallet/… use X-Client-Key. Mutations accept an Idempotency-Key header (exactly-once); top-up also accepts a stored instrument_id instead of a fresh token.

Double-entry ledger

Auth · Bearer api key

Method	Path	Description
GET	`/api/v1/ledger`	Recent immutable journal entries (balanced debits/credits).
GET	`/api/v1/ledger/balances`	Trial balance per account/currency + global debit/credit totals.

Network tokenization & account updater

Auth · Bearer api key

Method	Path	Description
POST	`/api/v1/instruments`	Network-tokenize a processor token into a reusable stored instrument.
GET	`/api/v1/instruments/{customer}`	List a customer's stored instruments.
POST	`/api/v1/instruments/{id}/updater`	Account-updater event (`reissued`/`expired`/`closed`) — refreshes the credential.

Token vault (PCI CDE)

Auth · Bearer api key

Method	Path	Description
POST	`/api/v1/vault/cards`	Vault a PAN: Luhn-validated, envelope-encrypted via KMS, returns an opaque routing token + masked PAN/BIN/brand. The cleartext PAN is never returned.
GET	`/api/v1/vault/cards/{id}`	Fetch the non-sensitive vault metadata (token, masked PAN, BIN, network, expiry, key version).

Detokenization is egress-only (to a processor) and never exposed over the merchant API.

Stored credentials & MIT

Auth · Bearer api key

Method	Path	Description
POST	`/api/v1/agreements`	Capture consent for a credential-on-file agreement against a vault token.
GET	`/api/v1/agreements` · `/{id}`	List agreements / fetch one.
POST	`/api/v1/agreements/{id}/activate`	Activate on the initial charge, recording the network transaction id.
POST	`/api/v1/agreements/{id}/mit`	Resolve the COF/MIT framing for a merchant-initiated charge (recurring/unscheduled/installment).
POST	`/api/v1/agreements/{id}/revoke`	Revoke consent.

3-D Secure 2

Auth · Bearer api key

Method	Path	Description
POST	`/api/v1/3ds`	Initiate authentication; the SCA engine + policy decide frictionless vs challenge. Returns flow, ECI/CAVV and liability-shift state.
GET	`/api/v1/3ds/{id}`	Fetch an authentication's current state.
POST	`/api/v1/3ds/{id}/challenge`	Resolve an outstanding challenge (`approve`/`fail`/`cancel`/`timeout`).

Settlement batches

Auth · Bearer api key

Method	Path	Description
POST	`/api/v1/batches/capture`	Add a captured amount to the open batch (opens one if none is open).
POST	`/api/v1/batches/close`	Close the open batch for settlement submission.
GET	`/api/v1/batches` · `/{id}`	List batches / fetch one.
POST	`/api/v1/batches/{id}/settle` · `/error`	Mark a closed batch funded, or rejected by the acquirer.

Disputes & chargebacks

Auth · Bearer api key

Method	Path	Description
POST	`/api/v1/disputes`	Open a dispute (chargeback).
GET	`/api/v1/disputes` · `/{id}`	List disputes / fetch one with its representment packet.
POST	`/api/v1/disputes/{id}/evidence`	Attach evidence.
POST	`/api/v1/disputes/{id}/represent`	Submit a representment (network-specific, e.g. Visa CE3.0).
POST	`/api/v1/disputes/{id}/accept` · `/resolve` · `/expire`	Concede / apply network ruling / lapse the deadline.

SCA, fraud & reconciliation

Auth · Bearer api key

Method	Path	Description
POST	`/api/v1/sca/preview`	PSD2 SCA decision for a context — exemption (low-value/TRA/MIT) vs 3-D Secure challenge.
GET	`/api/v1/fraud/score/{tx}`	Adaptive fraud probability + band + top signals.
POST	`/api/v1/fraud/feedback`	Label an outcome — online model update + consortium counter.
GET	`/api/v1/metrics` · `/insights` · `/anomalies`	BI metrics, AI summary, anomaly signals.
GET	`/api/v1/reconciliation`	Reconciliation summary; `POST` triggers a run.

Tamper-evident audit trail

Auth · Bearer api key

Method	Path	Description
GET	`/api/v1/audit`	Hash-chained audit entries (each commits to the previous entry's hash).
GET	`/api/v1/audit/verify`	Re-derive the chain and prove integrity: `{intact, entries, broken_at_seq}`.

Append-only; any edit, insert or deletion breaks the chain and is detected by verify — SOC 2 / PCI DSS §10 logging.

Security & admin

Auth · X-Admin-Key

Method	Path	Description
GET	`/api/v1/security/kms`	Envelope-encryption / KMS status (scheme, key version). Admin-only.
GET	`/api/v1/fraud/model`	Fraud model status (weights, training count). Admin-only.
GET	`/api/v1/admin/dlq`	List webhook deliveries that exhausted their retries (dead-letter queue).
POST	`/api/v1/admin/dlq/{id}/replay`	Requeue a dead-lettered delivery for another attempt.

Privileged endpoints require X-Admin-Key (constant-time check), separate from merchant auth.

Webhook subscriptions

Auth · Bearer api key

Method	Path	Description
POST	`/api/v1/webhooks`	Subscribe a URL + signing secret to outbound events.
GET	`/api/v1/webhooks`	List subscriptions (secret never returned).
DELETE	`/api/v1/webhooks/{id}`	Remove a subscription.

Deliveries carry X-Webhook-Timestamp and X-Webhook-Signature: t=<ts>,v1=<hmac> (HMAC-SHA256 of {ts}.{body} with your secret), so receivers can reject replays; retried by the outbox worker. Signing secrets are stored envelope-encrypted at rest.

Processor webhooks & health

Auth · signature / none

Method	Path	Description
POST	`/hooks/{processor}`	Inbound processor callback (confirms async QR / VA / e-wallet). Signature verified before parsing.
GET	`/health`	Liveness check. No auth.

Examples

1 · Create session (backend)

POST /api/v1/sessions
Authorization: Bearer ak_live_...
Content-Type: application/json

{
  "region": "north_america",
  "amount": "19.99",
  "currency": "USD",
  "methods": ["card","apple_pay","qr"],
  "mode": "sale"
}

→ 200
{
  "session_id": "0199...",
  "client_secret": "cs_3f9c...",
  "amount": "19.99",
  "currency": "USD",
  "methods": ["card","apple_pay","qr"]
}

2 · Pay (client)

POST /api/v1/client/pay
X-Client-Key: ck_live_...
Idempotency-Key: 0199...:card
Content-Type: application/json

{
  "session_id": "0199...",
  "client_secret": "cs_3f9c...",
  "method": "card",
  "processor_token": "PIxxxxx"
}

→ 200
{
  "id": "019e...",
  "status": "captured",
  "processor_name": "finix",
  "processor_reference": "TRxxxx",
  "amount": { "amount": "19.99", "currency": "USD" }
}

Errors

Status	Meaning
`401`	Missing / invalid api or client key
`403`	Origin not allowed for the client key
`409`	Concurrent modification — retry
`410`	Session expired or already used
`422`	Invalid transition / amount (e.g. refund exceeds remaining)
`502`	Processor error or circuit open