{
  "openapi": "3.1.0",
  "info": {
    "title": "PayGate API",
    "version": "1.0.0",
    "description": "Payment orchestration and per-tenant ledger for the products that run on PayGate.\n\nEvery response carries `x-request-id`, and an error envelope repeats it as `request_id`:\nquote that when reporting a failure, and the matching log line and `error_events` row can be found.\n\nMoney-moving POSTs require `Idempotency-Key`. Reusing a key with a different body is a `409`, never a second charge.\nProvider callbacks are recorded but never trusted; only a provider status query settles a payment."
  },
  "servers": [
    {
      "url": "http://127.0.0.1:4000"
    }
  ],
  "tags": [
    {
      "name": "payments",
      "description": "Intents, attempts and confirmation"
    },
    {
      "name": "payouts",
      "description": "Recipients, releases, settlements and withdrawals"
    },
    {
      "name": "hosted",
      "description": "Checkout pages, callbacks and the fallback console"
    },
    {
      "name": "auth",
      "description": "Client credentials and DPoP"
    },
    {
      "name": "system",
      "description": "Health and the reference itself"
    }
  ],
  "paths": {
    "/healthz": {
      "get": {
        "operationId": "get_healthz",
        "tags": [
          "system"
        ],
        "summary": "Liveness, admission statistics, and optionally ledger drift",
        "description": "`?full=1` adds a balanced-journal check for the first tenant. Expensive; not for a per-second probe.",
        "responses": {
          "200": {
            "description": "`{ ok, time, admission }`, plus `ledger_drift` when `full=1`."
          },
          "default": {
            "description": "Error envelope; `request_id` matches `x-request-id` and the server log line.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/openapi.json": {
      "get": {
        "operationId": "get_v1_openapi_json",
        "tags": [
          "system"
        ],
        "summary": "This document",
        "responses": {
          "200": {
            "description": "OpenAPI 3.1 JSON. Generated from the route table, not maintained by hand."
          },
          "default": {
            "description": "Error envelope; `request_id` matches `x-request-id` and the server log line.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/auth/token": {
      "post": {
        "operationId": "post_v1_auth_token",
        "tags": [
          "auth"
        ],
        "summary": "Exchange a client assertion for a short-lived access token",
        "description": "`grant_type=client_credentials&client_id=…&client_assertion=…` as a form body. The DPoP header carries the proof.",
        "security": [
          {
            "dpopProof": []
          }
        ],
        "responses": {
          "200": {
            "description": "`{ access_token, token_type, expires_in }`. Bearer tokens are never stored; every request is proven again."
          },
          "default": {
            "description": "Error envelope; `request_id` matches `x-request-id` and the server log line.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/payment_methods": {
      "get": {
        "operationId": "get_v1_payment_methods",
        "tags": [
          "payments"
        ],
        "summary": "Methods this tenant can use right now",
        "description": "Optional `?currency=KES`. The publishable key must come from a registered Origin.",
        "security": [
          {
            "publishableKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "`{ data: [{ id, name, inputs, hints? }] }`. A lane in maintenance is absent, not returned as unavailable."
          },
          "default": {
            "description": "Error envelope; `request_id` matches `x-request-id` and the server log line.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/payments": {
      "post": {
        "operationId": "post_v1_payments",
        "tags": [
          "payments"
        ],
        "summary": "Create a payment intent",
        "description": "`{ 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`.",
        "security": [
          {
            "accessToken": [],
            "dpopProof": []
          }
        ],
        "responses": {
          "200": {
            "description": "The payment, including `checkout_token` and `checkout_url`. Retrying the same key and body replays it."
          },
          "default": {
            "description": "Error envelope; `request_id` matches `x-request-id` and the server log line.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "get_v1_payments",
        "tags": [
          "payments"
        ],
        "summary": "List payments for the calling tenant",
        "description": "`?status=&limit=&cursor=`",
        "security": [
          {
            "accessToken": [],
            "dpopProof": []
          }
        ],
        "responses": {
          "200": {
            "description": "`{ data: Payment[] }`, newest first."
          },
          "default": {
            "description": "Error envelope; `request_id` matches `x-request-id` and the server log line.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/payments/{id}": {
      "get": {
        "operationId": "get_v1_payments_id",
        "tags": [
          "payments"
        ],
        "summary": "Read one payment and its attempts",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "accessToken": [],
            "dpopProof": []
          }
        ],
        "responses": {
          "200": {
            "description": "The payment, its attempts, and whether it is payout-eligible."
          },
          "default": {
            "description": "Error envelope; `request_id` matches `x-request-id` and the server log line.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/payments/{id}/confirm": {
      "post": {
        "operationId": "post_v1_payments_id_confirm",
        "tags": [
          "payments"
        ],
        "summary": "Start or resume the provider attempt",
        "description": "`{ method: 'mobile_money' | 'card', phone? }` plus `Idempotency-Key`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "accessToken": [],
            "dpopProof": []
          }
        ],
        "responses": {
          "200": {
            "description": "The payment in `processing`; `succeeded` only ever follows verified provider evidence."
          },
          "default": {
            "description": "Error envelope; `request_id` matches `x-request-id` and the server log line.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/payments/{id}/refresh": {
      "post": {
        "operationId": "post_v1_payments_id_refresh",
        "tags": [
          "payments"
        ],
        "summary": "Ask the provider for authoritative status",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "accessToken": [],
            "dpopProof": []
          }
        ],
        "responses": {
          "200": {
            "description": "The payment after asking the provider. This is the only path that settles, and it never trusts a callback body."
          },
          "default": {
            "description": "Error envelope; `request_id` matches `x-request-id` and the server log line.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/payments/{id}/cancel": {
      "post": {
        "operationId": "post_v1_payments_id_cancel",
        "tags": [
          "payments"
        ],
        "summary": "Cancel an unpaid payment intent",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "accessToken": [],
            "dpopProof": []
          }
        ],
        "responses": {
          "200": {
            "description": "The cancelled payment. A payment that already succeeded is a conflict, not a cancellation."
          },
          "default": {
            "description": "Error envelope; `request_id` matches `x-request-id` and the server log line.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/payment_links": {
      "post": {
        "operationId": "post_v1_payment_links",
        "tags": [
          "payments"
        ],
        "summary": "Create a payment link",
        "description": "`{ description, amount, currency? }`. The amount is fixed for the life of the link.",
        "security": [
          {
            "accessToken": [],
            "dpopProof": []
          }
        ],
        "responses": {
          "200": {
            "description": "The link, including the public `url` a buyer opens. Created in the credential's environment."
          },
          "default": {
            "description": "Error envelope; `request_id` matches `x-request-id` and the server log line.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "get_v1_payment_links",
        "tags": [
          "payments"
        ],
        "summary": "List payment links",
        "security": [
          {
            "accessToken": [],
            "dpopProof": []
          }
        ],
        "responses": {
          "200": {
            "description": "Links created by this app in the credential's environment, newest first, each with `paid_count` / `collected` for succeeded payments only."
          },
          "default": {
            "description": "Error envelope; `request_id` matches `x-request-id` and the server log line.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/payment_links/{id}": {
      "get": {
        "operationId": "get_v1_payment_links_id",
        "tags": [
          "payments"
        ],
        "summary": "Read a link and what it collected",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "accessToken": [],
            "dpopProof": []
          }
        ],
        "responses": {
          "200": {
            "description": "The link, its payments, and `paid_count` / `collected` for succeeded payments only."
          },
          "default": {
            "description": "Error envelope; `request_id` matches `x-request-id` and the server log line.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/payment_links/{id}/active": {
      "post": {
        "operationId": "post_v1_payment_links_id_active",
        "tags": [
          "payments"
        ],
        "summary": "Close or reopen a link",
        "description": "`{ active: boolean }`. Closing stops new payments and leaves existing ones alone.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "accessToken": [],
            "dpopProof": []
          }
        ],
        "responses": {
          "200": {
            "description": "The updated link."
          },
          "default": {
            "description": "Error envelope; `request_id` matches `x-request-id` and the server log line.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/sandbox/signup": {
      "post": {
        "operationId": "post_v1_sandbox_signup",
        "tags": [
          "system"
        ],
        "summary": "Create a sandbox app and return its credentials once",
        "description": "`{ app_name, email }`. Sandbox only: this route cannot mint a live client.",
        "responses": {
          "200": {
            "description": "`{ client_id, private_key, publishable_key, recovery_token, scopes, tenant }`. The private key and recovery token are shown once and never again."
          },
          "default": {
            "description": "Error envelope; `request_id` matches `x-request-id` and the server log line.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/sandbox/rotate": {
      "post": {
        "operationId": "post_v1_sandbox_rotate",
        "tags": [
          "system"
        ],
        "summary": "Replace the sandbox key pair",
        "description": "`{ recovery_token }`. The old client is revoked after the new one is registered.",
        "responses": {
          "200": {
            "description": "New credentials for the same tenant. The recovery token does not change."
          },
          "default": {
            "description": "Error envelope; `request_id` matches `x-request-id` and the server log line.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/sandbox/revoke": {
      "post": {
        "operationId": "post_v1_sandbox_revoke",
        "tags": [
          "system"
        ],
        "summary": "Revoke the sandbox client",
        "description": "`{ recovery_token }`.",
        "responses": {
          "200": {
            "description": "`{ revoked: true }`. Terminal: a revoked signup cannot be rotated."
          },
          "default": {
            "description": "Error envelope; `request_id` matches `x-request-id` and the server log line.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/releases": {
      "post": {
        "operationId": "post_v1_releases",
        "tags": [
          "payouts"
        ],
        "summary": "Release a settled payment to its seller",
        "description": "`{ recipient_id, reference }` plus `Idempotency-Key`.",
        "security": [
          {
            "accessToken": [],
            "dpopProof": []
          }
        ],
        "responses": {
          "200": {
            "description": "The payout instruction. Releasing twice returns the first instruction."
          },
          "default": {
            "description": "Error envelope; `request_id` matches `x-request-id` and the server log line.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/recipients": {
      "post": {
        "operationId": "post_v1_recipients",
        "tags": [
          "payouts"
        ],
        "summary": "Create a seller, pharmacy or lab that can be paid",
        "description": "`{ display_name, type, ... }`",
        "security": [
          {
            "accessToken": [],
            "dpopProof": []
          }
        ],
        "responses": {
          "200": {
            "description": "The recipient with its default payout mode."
          },
          "default": {
            "description": "Error envelope; `request_id` matches `x-request-id` and the server log line.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/recipients/{id}": {
      "get": {
        "operationId": "get_v1_recipients_id",
        "tags": [
          "payouts"
        ],
        "summary": "Read one recipient",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "accessToken": [],
            "dpopProof": []
          }
        ],
        "responses": {
          "200": {
            "description": "The recipient and its destinations (masked)."
          },
          "default": {
            "description": "Error envelope; `request_id` matches `x-request-id` and the server log line.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/recipients/{id}/payout_mode": {
      "patch": {
        "operationId": "patch_v1_recipients_id_payout_mode",
        "tags": [
          "payouts"
        ],
        "summary": "Change how this recipient is paid",
        "description": "`{ payout_mode: 'instant' | 'on_request' | 'scheduled' | 'manual' }`",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "accessToken": [],
            "dpopProof": []
          }
        ],
        "responses": {
          "200": {
            "description": "The updated recipient."
          },
          "default": {
            "description": "Error envelope; `request_id` matches `x-request-id` and the server log line.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/recipients/{id}/destinations": {
      "post": {
        "operationId": "post_v1_recipients_id_destinations",
        "tags": [
          "payouts"
        ],
        "summary": "Add a payout destination",
        "description": "`{ provider, msisdn? , ... }`",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "accessToken": [],
            "dpopProof": []
          }
        ],
        "responses": {
          "200": {
            "description": "The destination, with the identifier masked in responses."
          },
          "default": {
            "description": "Error envelope; `request_id` matches `x-request-id` and the server log line.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/recipients/{id}/balances": {
      "get": {
        "operationId": "get_v1_recipients_id_balances",
        "tags": [
          "payouts"
        ],
        "summary": "Pending, unreleased, available, reserved and paid for one recipient",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "accessToken": [],
            "dpopProof": []
          }
        ],
        "responses": {
          "200": {
            "description": "Amounts formatted for display plus minor units. `available` is what a payout may draw on."
          },
          "default": {
            "description": "Error envelope; `request_id` matches `x-request-id` and the server log line.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/settlements": {
      "post": {
        "operationId": "post_v1_settlements",
        "tags": [
          "payouts"
        ],
        "summary": "Create a payout instruction for a recipient",
        "description": "`{ recipient_id, amount_minor, reference }` plus `Idempotency-Key`. Above the approval threshold this waits for a second operator.",
        "security": [
          {
            "accessToken": [],
            "dpopProof": []
          }
        ],
        "responses": {
          "200": {
            "description": "The instruction in `pending_approval` or `approved`. Creating one is not paying one."
          },
          "default": {
            "description": "Error envelope; `request_id` matches `x-request-id` and the server log line.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "get_v1_settlements",
        "tags": [
          "payouts"
        ],
        "summary": "List payout instructions",
        "security": [
          {
            "accessToken": [],
            "dpopProof": []
          }
        ],
        "responses": {
          "200": {
            "description": "`{ data: Instruction[] }` with status and maker–checker state."
          },
          "default": {
            "description": "Error envelope; `request_id` matches `x-request-id` and the server log line.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/settlements/{id}": {
      "get": {
        "operationId": "get_v1_settlements_id",
        "tags": [
          "payouts"
        ],
        "summary": "Read one payout instruction",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "accessToken": [],
            "dpopProof": []
          }
        ],
        "responses": {
          "200": {
            "description": "The instruction, its approvals and its execution result."
          },
          "default": {
            "description": "Error envelope; `request_id` matches `x-request-id` and the server log line.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/settlements/{id}/executed": {
      "post": {
        "operationId": "post_v1_settlements_id_executed",
        "tags": [
          "payouts"
        ],
        "summary": "Record the app's signed-mandate execution result",
        "description": "`{ status: 'succeeded' | 'failed', provider_ref?, reason? }`, authenticated as the executor.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "accessToken": [],
            "dpopProof": []
          }
        ],
        "responses": {
          "200": {
            "description": "The instruction as recorded. A failure is recorded as a failure; it is never retried automatically."
          },
          "default": {
            "description": "Error envelope; `request_id` matches `x-request-id` and the server log line.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/withdrawals": {
      "post": {
        "operationId": "post_v1_withdrawals",
        "tags": [
          "payouts"
        ],
        "summary": "A recipient-initiated withdrawal request",
        "description": "`{ recipient_id, amount_minor }` plus `Idempotency-Key`.",
        "security": [
          {
            "accessToken": [],
            "dpopProof": []
          }
        ],
        "responses": {
          "200": {
            "description": "A request, not a payment: an operator still approves and executes it."
          },
          "default": {
            "description": "Error envelope; `request_id` matches `x-request-id` and the server log line.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/withdrawals/{id}": {
      "get": {
        "operationId": "get_v1_withdrawals_id",
        "tags": [
          "payouts"
        ],
        "summary": "Read one withdrawal request",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "accessToken": [],
            "dpopProof": []
          }
        ],
        "responses": {
          "200": {
            "description": "Its state and the instruction it became, if any."
          },
          "default": {
            "description": "Error envelope; `request_id` matches `x-request-id` and the server log line.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/providers/health": {
      "get": {
        "operationId": "get_v1_providers_health",
        "tags": [
          "system"
        ],
        "summary": "Observed health for every provider lane",
        "description": "Merchant-authenticated. The operator view is a separate, internal surface and is not part of this reference.",
        "security": [
          {
            "accessToken": [],
            "dpopProof": []
          }
        ],
        "responses": {
          "200": {
            "description": "One row per provider, capability and currency, with the state routing uses."
          },
          "default": {
            "description": "Error envelope; `request_id` matches `x-request-id` and the server log line.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/callbacks/{provider}": {
      "post": {
        "operationId": "post_v1_callbacks_provider",
        "tags": [
          "callbacks"
        ],
        "summary": "Provider callback, authenticated by the provider's own signature",
        "description": "The provider's native body (Daraja `Body.stkCallback`, Paystack JSON). Verified before anything is recorded.",
        "parameters": [
          {
            "name": "provider",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "`{ accepted, verified, status }`. A callback is a hint; `refresh` is what settles."
          },
          "default": {
            "description": "Error envelope; `request_id` matches `x-request-id` and the server log line.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/sequin/events": {
      "post": {
        "operationId": "post_v1_sequin_events",
        "tags": [
          "callbacks"
        ],
        "summary": "Sequin change-data ingress, authenticated by HMAC over the raw body",
        "description": "Sequin's webhook batch, `{ data: [ { action, record, metadata } ] }`, signed as `x-sequin-signature`. Watched tables: `payment_poll_queue` and `webhook_outbox`.",
        "responses": {
          "200": {
            "description": "`{ 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": {
            "description": "Error envelope; `request_id` matches `x-request-id` and the server log line.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/l/{token}": {
      "get": {
        "operationId": "get_l_token",
        "tags": [
          "hosted"
        ],
        "summary": "Payment link page",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTML. Shows the description, the fixed amount and one Pay button; creates nothing."
          },
          "default": {
            "description": "Error envelope; `request_id` matches `x-request-id` and the server log line.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/l/{token}/pay": {
      "post": {
        "operationId": "post_l_token_pay",
        "tags": [
          "hosted"
        ],
        "summary": "Create the payment behind a link and open checkout",
        "description": "No body. A form post is the buyer's explicit consent to pay.",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A redirect to hosted checkout. Each post creates its own payment."
          },
          "default": {
            "description": "Error envelope; `request_id` matches `x-request-id` and the server log line.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/c/{token}": {
      "get": {
        "operationId": "get_c_token",
        "tags": [
          "hosted"
        ],
        "summary": "Hosted checkout page, or the payment's result once terminal",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTML. The token is single-use for a payment and scoped to it."
          },
          "default": {
            "description": "Error envelope; `request_id` matches `x-request-id` and the server log line.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/c/{token}/pay": {
      "post": {
        "operationId": "post_c_token_pay",
        "tags": [
          "hosted"
        ],
        "summary": "Buyer picks a method and pays without leaving the page",
        "description": "`{ 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.",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "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": {
            "description": "Error envelope; `request_id` matches `x-request-id` and the server log line.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/c/{token}/card": {
      "get": {
        "operationId": "get_c_token_card",
        "tags": [
          "hosted"
        ],
        "summary": "Hosted card fallback, for connectors without a direct charge",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTML. The provider's PCI-scoped fields; no PAN reaches PayGate."
          },
          "default": {
            "description": "Error envelope; `request_id` matches `x-request-id` and the server log line.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "post_c_token_card",
        "tags": [
          "hosted"
        ],
        "summary": "Start a hosted card attempt",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A redirect to the provider's card page. Not used when card details were submitted to `/pay`."
          },
          "default": {
            "description": "Error envelope; `request_id` matches `x-request-id` and the server log line.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/c/{token}/card/charge": {
      "post": {
        "operationId": "post_c_token_card_charge",
        "tags": [
          "hosted"
        ],
        "summary": "Charge a card the browser encrypted, without leaving the page",
        "description": "`{ encrypted }` — the provider's ciphertext; no PAN is sent to this origin.",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "`{ status, attempt_id, step_up, redirect_url }`. `step_up` means the bank wants a PIN or an OTP, which the page renders itself."
          },
          "default": {
            "description": "Error envelope; `request_id` matches `x-request-id` and the server log line.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/c/{token}/card/authorize": {
      "post": {
        "operationId": "post_c_token_card_authorize",
        "tags": [
          "hosted"
        ],
        "summary": "Finish a direct card charge that needs a second factor",
        "description": "`{ 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.",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The same page with the next required field, or a redirect to the status page. The attempt is reused, never recreated."
          },
          "default": {
            "description": "Error envelope; `request_id` matches `x-request-id` and the server log line.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/c/{token}/card/return": {
      "get": {
        "operationId": "get_c_token_card_return",
        "tags": [
          "hosted"
        ],
        "summary": "Return from the card page",
        "description": "The provider's reference in the query.",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A redirect to the status page. Arriving here proves nothing; the server asks the provider."
          },
          "default": {
            "description": "Error envelope; `request_id` matches `x-request-id` and the server log line.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/c/{token}/status": {
      "get": {
        "operationId": "get_c_token_status",
        "tags": [
          "hosted"
        ],
        "summary": "Status page for a payment",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTML that polls the payment. Its verdict comes from the API, never from the URL."
          },
          "default": {
            "description": "Error envelope; `request_id` matches `x-request-id` and the server log line.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/c/{token}/simulate": {
      "post": {
        "operationId": "post_c_token_simulate",
        "tags": [
          "hosted"
        ],
        "summary": "Sandbox only: make the simulated provider settle",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "`{ ok: true }` or 404 in production, where the simulator is not registered at all."
          },
          "default": {
            "description": "Error envelope; `request_id` matches `x-request-id` and the server log line.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/": {
      "get": {
        "operationId": "get_root",
        "tags": [
          "system"
        ],
        "summary": "Service banner",
        "responses": {
          "200": {
            "description": "The product name and version."
          },
          "default": {
            "description": "Error envelope; `request_id` matches `x-request-id` and the server log line.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "accessToken": {
        "type": "http",
        "scheme": "bearer",
        "description": "Short-lived access token from `POST /v1/auth/token`. Never stored in a browser."
      },
      "dpopProof": {
        "type": "apiKey",
        "in": "header",
        "name": "DPoP",
        "description": "An Ed25519-signed proof over the method, URL, timestamp and a one-time `jti`."
      },
      "publishableKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "`pk_sandbox_…` / `pk_live_…`. Bound to registered origins; can read methods and nothing else."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable identifier. Branch on this, never on the message."
              },
              "message": {
                "type": "string",
                "description": "Human-readable, safe to log."
              },
              "details": {
                "type": "object",
                "additionalProperties": true
              },
              "request_id": {
                "type": "string",
                "description": "Same value as the `x-request-id` response header."
              }
            }
          }
        }
      }
    }
  }
}
