Console

API reference · OpenAPI 3.1.0

PayGate API

Every route, parameter, body and response, generated from the same document the API is built against. Amounts are integers in minor units; every write takes an Idempotency-Key.

Base URL
https://api.paygate.example
Version
1.0.0
Routes
44 operations · 40 paths
Environments
Sandbox · Live

Payment orchestration and per-tenant ledger for the products that run on PayGate.

Every response carries x-request-id, and an error envelope repeats it as request_id: quote that when reporting a failure, and the matching log line and error_events row can be found.

Money-moving POSTs require Idempotency-Key. Reusing a key with a different body is a 409, never a second charge. Provider callbacks are recorded but never trusted; only a provider status query settles a payment.

Credentials

A request is admitted by its client credential and proof, then checked against the resource owner. Send both where an operation lists two.

accessToken

http · bearer

Short-lived access token from POST /v1/auth/token. Never stored in a browser.

dpopProof

apiKey · header header <code>DPoP</code>

An Ed25519-signed proof over the method, URL, timestamp and a one-time jti.

publishableKey

http · bearer

pk_sandbox_… / pk_live_…. Bound to registered origins; can read methods and nothing else.

Reference

Grouped by area. Each route shows the credential it needs; the credential itself is described above, and the raw document is at /openapi.json.

payments

Intents, attempts and confirmation

get /v1/payment_methods #

Methods this tenant can use right now

Optional ?currency=KES. The publishable key must come from a registered Origin.

Credential publishableKey

Responses

200

{ data: [{ id, name, inputs, hints? }] }. A lane in maintenance is absent, not returned as unavailable.

default

Error envelope; request_id matches x-request-id and the server log line.

Error
get /v1/payments #

List payments for the calling tenant

?status=&limit=&cursor=

Credential accessToken + dpopProof

Responses

200

{ data: Payment[] }, newest first.

default

Error envelope; request_id matches x-request-id and the server log line.

Error
post /v1/payments #

Create a payment intent

{ amount_minor, currency, reference, recipient_id?, splits?, metadata? } plus Idempotency-Key. splits is [{ recipient_id, amount }] and its shares must sum to the amount; it is mutually exclusive with recipient_id.

Credential accessToken + dpopProof

Responses

200

The payment, including checkout_token and checkout_url. Retrying the same key and body replays it.

default

Error envelope; request_id matches x-request-id and the server log line.

Error
get /v1/payments/{id} #

Read one payment and its attempts

Credential accessToken + dpopProof

Parameters

path idrequired
string

Responses

200

The payment, its attempts, and whether it is payout-eligible.

default

Error envelope; request_id matches x-request-id and the server log line.

Error
post /v1/payments/{id}/confirm #

Start or resume the provider attempt

{ method: 'mobile_money' | 'card', phone? } plus Idempotency-Key.

Credential accessToken + dpopProof

Parameters

path idrequired
string

Responses

200

The payment in processing; succeeded only ever follows verified provider evidence.

default

Error envelope; request_id matches x-request-id and the server log line.

Error
post /v1/payments/{id}/refresh #

Ask the provider for authoritative status

Credential accessToken + dpopProof

Parameters

path idrequired
string

Responses

200

The payment after asking the provider. This is the only path that settles, and it never trusts a callback body.

default

Error envelope; request_id matches x-request-id and the server log line.

Error
post /v1/payments/{id}/cancel #

Cancel an unpaid payment intent

Credential accessToken + dpopProof

Parameters

path idrequired
string

Responses

200

The cancelled payment. A payment that already succeeded is a conflict, not a cancellation.

default

Error envelope; request_id matches x-request-id and the server log line.

Error
post /v1/payment_links #

Create a payment link

{ description, amount, currency? }. The amount is fixed for the life of the link.

Credential accessToken + dpopProof

Responses

200

The link, including the public url a buyer opens. Created in the credential's environment.

default

Error envelope; request_id matches x-request-id and the server log line.

Error
post /v1/payment_links/{id}/active #

Close or reopen a link

{ active: boolean }. Closing stops new payments and leaves existing ones alone.

Credential accessToken + dpopProof

Parameters

path idrequired
string

Responses

200

The updated link.

default

Error envelope; request_id matches x-request-id and the server log line.

Error

payouts

Recipients, releases, settlements and withdrawals

post /v1/releases #

Release a settled payment to its seller

{ recipient_id, reference } plus Idempotency-Key.

Credential accessToken + dpopProof

Responses

200

The payout instruction. Releasing twice returns the first instruction.

default

Error envelope; request_id matches x-request-id and the server log line.

Error
post /v1/recipients #

Create a seller, pharmacy or lab that can be paid

{ display_name, type, ... }

Credential accessToken + dpopProof

Responses

200

The recipient with its default payout mode.

default

Error envelope; request_id matches x-request-id and the server log line.

Error
get /v1/recipients/{id} #

Read one recipient

Credential accessToken + dpopProof

Parameters

path idrequired
string

Responses

200

The recipient and its destinations (masked).

default

Error envelope; request_id matches x-request-id and the server log line.

Error
patch /v1/recipients/{id}/payout_mode #

Change how this recipient is paid

{ payout_mode: 'instant' | 'on_request' | 'scheduled' | 'manual' }

Credential accessToken + dpopProof

Parameters

path idrequired
string

Responses

200

The updated recipient.

default

Error envelope; request_id matches x-request-id and the server log line.

Error
post /v1/recipients/{id}/destinations #

Add a payout destination

{ provider, msisdn? , ... }

Credential accessToken + dpopProof

Parameters

path idrequired
string

Responses

200

The destination, with the identifier masked in responses.

default

Error envelope; request_id matches x-request-id and the server log line.

Error
get /v1/recipients/{id}/balances #

Pending, unreleased, available, reserved and paid for one recipient

Credential accessToken + dpopProof

Parameters

path idrequired
string

Responses

200

Amounts formatted for display plus minor units. available is what a payout may draw on.

default

Error envelope; request_id matches x-request-id and the server log line.

Error
get /v1/settlements #

List payout instructions

Credential accessToken + dpopProof

Responses

200

{ data: Instruction[] } with status and maker–checker state.

default

Error envelope; request_id matches x-request-id and the server log line.

Error
post /v1/settlements #

Create a payout instruction for a recipient

{ recipient_id, amount_minor, reference } plus Idempotency-Key. Above the approval threshold this waits for a second operator.

Credential accessToken + dpopProof

Responses

200

The instruction in pending_approval or approved. Creating one is not paying one.

default

Error envelope; request_id matches x-request-id and the server log line.

Error
get /v1/settlements/{id} #

Read one payout instruction

Credential accessToken + dpopProof

Parameters

path idrequired
string

Responses

200

The instruction, its approvals and its execution result.

default

Error envelope; request_id matches x-request-id and the server log line.

Error
post /v1/settlements/{id}/executed #

Record the app's signed-mandate execution result

{ status: 'succeeded' | 'failed', provider_ref?, reason? }, authenticated as the executor.

Credential accessToken + dpopProof

Parameters

path idrequired
string

Responses

200

The instruction as recorded. A failure is recorded as a failure; it is never retried automatically.

default

Error envelope; request_id matches x-request-id and the server log line.

Error
post /v1/withdrawals #

A recipient-initiated withdrawal request

{ recipient_id, amount_minor } plus Idempotency-Key.

Credential accessToken + dpopProof

Responses

200

A request, not a payment: an operator still approves and executes it.

default

Error envelope; request_id matches x-request-id and the server log line.

Error
get /v1/withdrawals/{id} #

Read one withdrawal request

Credential accessToken + dpopProof

Parameters

path idrequired
string

Responses

200

Its state and the instruction it became, if any.

default

Error envelope; request_id matches x-request-id and the server log line.

Error

hosted

Checkout pages, callbacks and the fallback console

get /l/{token} #

Payment link page

Credential none

Parameters

path tokenrequired
string

Responses

200

HTML. Shows the description, the fixed amount and one Pay button; creates nothing.

default

Error envelope; request_id matches x-request-id and the server log line.

Error
post /l/{token}/pay #

Create the payment behind a link and open checkout

No body. A form post is the buyer's explicit consent to pay.

Credential none

Parameters

path tokenrequired
string

Responses

200

A redirect to hosted checkout. Each post creates its own payment.

default

Error envelope; request_id matches x-request-id and the server log line.

Error
get /c/{token} #

Hosted checkout page, or the payment's result once terminal

Credential none

Parameters

path tokenrequired
string

Responses

200

HTML. The token is single-use for a payment and scoped to it.

default

Error envelope; request_id matches x-request-id and the server log line.

Error
post /c/{token}/pay #

Buyer picks a method and pays without leaving the page

{ method: 'mobile_money', phone } or { method: 'card', card_number, card_expiry, card_cvv, card_holder }. Card fields are optional; a request without them falls back to the hosted card step.

Credential none

Parameters

path tokenrequired
string

Responses

200

A redirect to the waiting page, or the confirm-your-card page when the issuer wants a PIN, an OTP or a billing address.

default

Error envelope; request_id matches x-request-id and the server log line.

Error
get /c/{token}/card #

Hosted card fallback, for connectors without a direct charge

Credential none

Parameters

path tokenrequired
string

Responses

200

HTML. The provider's PCI-scoped fields; no PAN reaches PayGate.

default

Error envelope; request_id matches x-request-id and the server log line.

Error
post /c/{token}/card #

Start a hosted card attempt

Credential none

Parameters

path tokenrequired
string

Responses

200

A redirect to the provider's card page. Not used when card details were submitted to /pay.

default

Error envelope; request_id matches x-request-id and the server log line.

Error
post /c/{token}/card/charge #

Charge a card the browser encrypted, without leaving the page

{ encrypted } — the provider's ciphertext; no PAN is sent to this origin.

Credential none

Parameters

path tokenrequired
string

Responses

200

{ status, attempt_id, step_up, redirect_url }. step_up means the bank wants a PIN or an OTP, which the page renders itself.

default

Error envelope; request_id matches x-request-id and the server log line.

Error
post /c/{token}/card/authorize #

Finish a direct card charge that needs a second factor

{ attempt_id, mode, auth_<field> } for a server-captured card, or { attempt_id, encrypted } when the browser re-encrypted the whole payload with the step-up fields inside it.

Credential none

Parameters

path tokenrequired
string

Responses

200

The same page with the next required field, or a redirect to the status page. The attempt is reused, never recreated.

default

Error envelope; request_id matches x-request-id and the server log line.

Error
get /c/{token}/card/return #

Return from the card page

The provider's reference in the query.

Credential none

Parameters

path tokenrequired
string

Responses

200

A redirect to the status page. Arriving here proves nothing; the server asks the provider.

default

Error envelope; request_id matches x-request-id and the server log line.

Error
get /c/{token}/status #

Status page for a payment

Credential none

Parameters

path tokenrequired
string

Responses

200

HTML that polls the payment. Its verdict comes from the API, never from the URL.

default

Error envelope; request_id matches x-request-id and the server log line.

Error
post /c/{token}/simulate #

Sandbox only: make the simulated provider settle

Credential none

Parameters

path tokenrequired
string

Responses

200

{ ok: true } or 404 in production, where the simulator is not registered at all.

default

Error envelope; request_id matches x-request-id and the server log line.

Error

auth

Client credentials and DPoP

post /v1/auth/token #

Exchange a client assertion for a short-lived access token

grant_type=client_credentials&client_id=…&client_assertion=… as a form body. The DPoP header carries the proof.

Credential dpopProof

Responses

200

{ access_token, token_type, expires_in }. Bearer tokens are never stored; every request is proven again.

default

Error envelope; request_id matches x-request-id and the server log line.

Error

system

Health and the reference itself

get /healthz #

Liveness, admission statistics, and optionally ledger drift

?full=1 adds a balanced-journal check for the first tenant. Expensive; not for a per-second probe.

Credential none

Responses

200

{ ok, time, admission }, plus ledger_drift when full=1.

default

Error envelope; request_id matches x-request-id and the server log line.

Error
get /v1/openapi.json #

This document

Credential none

Responses

200

OpenAPI 3.1 JSON. Generated from the route table, not maintained by hand.

default

Error envelope; request_id matches x-request-id and the server log line.

Error
post /v1/sandbox/signup #

Create a sandbox app and return its credentials once

{ app_name, email }. Sandbox only: this route cannot mint a live client.

Credential none

Responses

200

{ client_id, private_key, publishable_key, recovery_token, scopes, tenant }. The private key and recovery token are shown once and never again.

default

Error envelope; request_id matches x-request-id and the server log line.

Error
post /v1/sandbox/rotate #

Replace the sandbox key pair

{ recovery_token }. The old client is revoked after the new one is registered.

Credential none

Responses

200

New credentials for the same tenant. The recovery token does not change.

default

Error envelope; request_id matches x-request-id and the server log line.

Error
post /v1/sandbox/revoke #

Revoke the sandbox client

{ recovery_token }.

Credential none

Responses

200

{ revoked: true }. Terminal: a revoked signup cannot be rotated.

default

Error envelope; request_id matches x-request-id and the server log line.

Error
get /v1/providers/health #

Observed health for every provider lane

Merchant-authenticated. The operator view is a separate, internal surface and is not part of this reference.

Credential accessToken + dpopProof

Responses

200

One row per provider, capability and currency, with the state routing uses.

default

Error envelope; request_id matches x-request-id and the server log line.

Error
get / #

Service banner

Credential none

Responses

200

The product name and version.

default

Error envelope; request_id matches x-request-id and the server log line.

Error

callbacks

post /v1/callbacks/{provider} #

Provider callback, authenticated by the provider's own signature

The provider's native body (Daraja Body.stkCallback, Paystack JSON). Verified before anything is recorded.

Credential none

Parameters

path providerrequired
string

Responses

200

{ accepted, verified, status }. A callback is a hint; refresh is what settles.

default

Error envelope; request_id matches x-request-id and the server log line.

Error
post /v1/sequin/events #

Sequin change-data ingress, authenticated by HMAC over the raw body

Sequin's webhook batch, { data: [ { action, record, metadata } ] }, signed as x-sequin-signature. Watched tables: payment_poll_queue and webhook_outbox.

Credential none

Responses

200

{ accepted, processed, skipped, failed }. An accelerator only: the reconciliation sweep and the delivery loop still run, so a missed delivery costs latency, not a payment.

default

Error envelope; request_id matches x-request-id and the server log line.

Error

Schemas

Shared shapes referenced by the responses above.

schema Error #
errorrequired
object
coderequired
string

Stable identifier. Branch on this, never on the message.

messagerequired
string

Human-readable, safe to log.

details
object
request_id
string

Same value as the x-request-id response header.

Machine-readable

This page is a view; the document is the contract. Agents should start with the plain-text guide, then read the spec.

  • /openapi.jsonOpenAPI 3.1, 40 paths. Also served by the API at /v1/openapi.json.
  • /llms.txtThe index an agent reads first: environments, statuses, signing, the SDK list.
  • /llms-full.txtThe complete integration guide in plain text.
Back to index