API Reference

The Payment Gateway exposes two HTTP surfaces, but they do not serve the same audience. On the hosted platform, api.payment-gateway.app is the Admin API and webhook.payment-gateway.app is the Main Backend — see Hostnames & DNS conventions.

All endpoints return JSON. All timestamps are ISO 8601 UTC strings.

[!NOTE] The Admin Backend mounts routes under /api/v1. The default payment-gateway-reverseproxy/Caddyfile rewrites /v1/* → /api/v1/* on {$ADMIN_BACKEND_DOMAIN} — see Caddy reverse proxy.

[!IMPORTANT] For almost all merchant integrations, use the Admin API with either an Organization API key or, for platform-wide automation, a System API key. The Main Backend endpoints exist mainly to support hosted checkout pages, customer portal flows, and payment-provider callbacks.

For a step-by-step order of operations (hostnames → provider webhooks → API key → POST checkout → optional IPN), see Server integration checklist.

Authentication

Admin API — API Key (Recommended for Server-to-Server)

Include your Organization API Key as a Bearer token:

Authorization: Bearer sk_live_keyid.secret

API keys have the format sk_live_<keyId>.<secret> (live) or sk_test_<keyId>.<secret> (test). The key ID and secret are dot-separated.

Keys are organization-scoped and carry granular scope grants (e.g., checkout:create, transaction:read). A key without the required scope for an endpoint returns 403 Forbidden.

System API keys use the same Bearer format, but they are reserved for global administrative automation rather than day-to-day merchant integrations.

[!CAUTION] API keys are shown only once at creation time. Store them in a secrets manager (AWS Secrets Manager, HashiCorp Vault, etc.), never in source code.

Admin API — JWT (Dashboard Sessions)

The Admin Panel uses short-lived JWTs issued after WebAuthn authentication. Pass them as:

Authorization: Bearer eyJhbGci...

JWTs expire after a configured interval. Use POST /api/v1/auth/refresh-token to obtain a new token before expiry.

Main Backend Public Endpoints

Checkout session retrieval (GET /api/v1/checkouts/:id) and portal OTP flows use public endpoints. Webhook endpoints (POST /hooks/:type/:providerId) verify request authenticity via provider-specific signature headers (Stripe-Signature, Webhook-Signature for GoCardless).

Rate Limiting

Rate-limited responses return 429 Too Many Requests with a Retry-After header.

Limits are configurable via MPG_RATE_LIMIT_* environment variables. Your own server IP can be whitelisted via MPG_RATE_LIMIT_WHITELIST.

Error Responses

All errors follow a consistent envelope:

{
  "error": "human-readable error message"
}

Request IDs

Every response includes an X-Request-ID header with a unique identifier. Include this ID when reporting issues.

Pagination

List endpoints support pagination via page and limit query parameters:

GET /api/v1/transactions?page=1&limit=50

Default page size varies by endpoint. Maximum is typically 100 items.

Health Endpoints

Both backends expose health check endpoints (no authentication required):

GET /health          # Shallow — returns 200 if the process is running
GET /internal/health # Deep — dependency checks (MongoDB is critical; cache and other checks may be non-critical)

See Monitoring for how partial failures map to HTTP status and response bodies.