{
    "openapi": "3.0.3",
    "info": {
        "title": "GatePay Merchant API",
        "version": "1.0.0",
        "description": "Accept mobile money (MTN MoMo, Airtel Money) and card payments. Two ways to collect: a hosted payment link (POST /v1/payments) or a direct mobile money PIN prompt with no redirect (POST /v1/collections).\n\n**Authentication.** Every request is signed. Get a 15-minute access token with POST /v1/auth/token (send X-Client-Id and a request signature), then call the API with `Authorization: Bearer <token>` plus a fresh signature on each call.\n\n**Signature.** canonical = METHOD + \"\\n\" + PATH_AND_QUERY + \"\\n\" + TIMESTAMP + \"\\n\" + NONCE + \"\\n\" + hex(SHA-256(raw body)); X-GatePay-Signature = lower-case hex HMAC-SHA256(client_secret, canonical). The timestamp must be within 5 minutes of GatePay time and each nonce may be used once. The client secret is never sent.\n\n**Responses** use one envelope: `{\"response\": {\"status\": {\"code\", \"message\"}, \"records\": {\"code\", ...}}}` where records.code is a stable machine-readable result.\n\nSample code in C#, Java, Python and PHP, webhooks and sandbox test numbers: see the written API documentation at /api-docs."
    },
    "servers": [
        {
            "url": "https://uatstage.gatepay.co.zm/api",
            "description": "GatePay"
        }
    ],
    "tags": [
        {
            "name": "Authentication"
        },
        {
            "name": "Payment links",
            "description": "Hosted checkout: redirect the customer to a GatePay payment page."
        },
        {
            "name": "Mobile money (no redirect)",
            "description": "Push a PIN prompt straight to the customer's phone."
        },
        {
            "name": "Transactions"
        }
    ],
    "paths": {
        "/v1/auth/token": {
            "post": {
                "tags": [
                    "Authentication"
                ],
                "summary": "Get an access token (15 minutes)",
                "security": [],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/ClientId"
                    },
                    {
                        "$ref": "#/components/parameters/Timestamp"
                    },
                    {
                        "$ref": "#/components/parameters/Nonce"
                    },
                    {
                        "$ref": "#/components/parameters/Signature"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "mode"
                                ],
                                "properties": {
                                    "mode": {
                                        "type": "string",
                                        "enum": [
                                            "sandbox",
                                            "live"
                                        ]
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Token issued",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "response": {
                                            "type": "object",
                                            "properties": {
                                                "status": {
                                                    "type": "object",
                                                    "properties": {
                                                        "code": {
                                                            "type": "integer"
                                                        },
                                                        "message": {
                                                            "type": "string"
                                                        }
                                                    }
                                                },
                                                "records": {
                                                    "type": "object",
                                                    "properties": {
                                                        "code": {
                                                            "type": "string",
                                                            "example": "token_issued"
                                                        },
                                                        "access_token": {
                                                            "type": "string"
                                                        },
                                                        "token_type": {
                                                            "type": "string",
                                                            "example": "Bearer"
                                                        },
                                                        "expires_in": {
                                                            "type": "integer",
                                                            "example": 900
                                                        },
                                                        "mode": {
                                                            "type": "string",
                                                            "example": "sandbox"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing/invalid signature, unknown client, or replayed nonce",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Credentials do not match the mode, source IP not allowed, or merchant not active",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v1/payments": {
            "post": {
                "tags": [
                    "Payment links"
                ],
                "summary": "Create a payment link (hosted checkout)",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/Timestamp"
                    },
                    {
                        "$ref": "#/components/parameters/Nonce"
                    },
                    {
                        "$ref": "#/components/parameters/Signature"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/CreatePayment"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Payment link created",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "response": {
                                            "type": "object",
                                            "properties": {
                                                "status": {
                                                    "type": "object",
                                                    "properties": {
                                                        "code": {
                                                            "type": "integer"
                                                        },
                                                        "message": {
                                                            "type": "string"
                                                        }
                                                    }
                                                },
                                                "records": {
                                                    "type": "object",
                                                    "properties": {
                                                        "code": {
                                                            "type": "string",
                                                            "example": "payment_link_created"
                                                        },
                                                        "transaction_id": {
                                                            "type": "string"
                                                        },
                                                        "reference": {
                                                            "type": "string"
                                                        },
                                                        "mode": {
                                                            "type": "string"
                                                        },
                                                        "status": {
                                                            "$ref": "#/components/schemas/Status"
                                                        },
                                                        "amount": {
                                                            "type": "string",
                                                            "example": "100.00000000"
                                                        },
                                                        "currency": {
                                                            "type": "string",
                                                            "example": "ZMW"
                                                        },
                                                        "payment_methods": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "string"
                                                            }
                                                        },
                                                        "payment_url": {
                                                            "type": "string",
                                                            "format": "uri"
                                                        },
                                                        "expires_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "metadata": {
                                                            "type": "object",
                                                            "additionalProperties": true
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Invalid token or signature",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "reference_conflict: the reference was used with different details",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "validation_error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v1/payments/status": {
            "get": {
                "tags": [
                    "Payment links"
                ],
                "summary": "Status of a payment by your reference",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "mode",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "sandbox",
                                "live"
                            ]
                        }
                    },
                    {
                        "name": "reference",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "maxLength": 100
                        }
                    },
                    {
                        "$ref": "#/components/parameters/Timestamp"
                    },
                    {
                        "$ref": "#/components/parameters/Nonce"
                    },
                    {
                        "$ref": "#/components/parameters/Signature"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Status retrieved",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "response": {
                                            "type": "object",
                                            "properties": {
                                                "status": {
                                                    "type": "object",
                                                    "properties": {
                                                        "code": {
                                                            "type": "integer"
                                                        },
                                                        "message": {
                                                            "type": "string"
                                                        }
                                                    }
                                                },
                                                "records": {
                                                    "type": "object",
                                                    "properties": {
                                                        "code": {
                                                            "type": "string",
                                                            "example": "transaction_status_retrieved"
                                                        },
                                                        "trx_reference": {
                                                            "type": "string"
                                                        },
                                                        "reference": {
                                                            "type": "string"
                                                        },
                                                        "status": {
                                                            "$ref": "#/components/schemas/Status"
                                                        },
                                                        "mode": {
                                                            "type": "string"
                                                        },
                                                        "provider": {
                                                            "type": "string",
                                                            "enum": [
                                                                "mtn",
                                                                "airtel"
                                                            ]
                                                        },
                                                        "channel": {
                                                            "type": "string",
                                                            "example": "direct_api"
                                                        },
                                                        "payer_phone": {
                                                            "type": "string",
                                                            "example": "+260961***567"
                                                        },
                                                        "amount": {
                                                            "type": "string",
                                                            "example": "250.00000000"
                                                        },
                                                        "currency": {
                                                            "type": "string",
                                                            "example": "ZMW"
                                                        },
                                                        "payment_method": {
                                                            "type": "string"
                                                        },
                                                        "description": {
                                                            "type": "string"
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "message": {
                                                            "type": "string"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Invalid token or signature",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "No payment with this reference",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "validation_error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v1/collections": {
            "post": {
                "tags": [
                    "Mobile money (no redirect)"
                ],
                "summary": "Push a mobile money PIN prompt to the customer's phone",
                "description": "Sending the same reference again returns the existing payment (no second prompt). The same phone paying the same amount again within 1 minute under another reference returns 409 repeat_payment_confirmation_required: the customer receives a 6-digit code; send the same request again with repeat_confirmation_token and repeat_confirmation_code.",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/Timestamp"
                    },
                    {
                        "$ref": "#/components/parameters/Nonce"
                    },
                    {
                        "$ref": "#/components/parameters/Signature"
                    },
                    {
                        "name": "X-Customer-IP",
                        "in": "header",
                        "required": false,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Your customer's IP address (fraud monitoring)."
                    },
                    {
                        "name": "X-Device-Id",
                        "in": "header",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "maxLength": 100
                        },
                        "description": "Your customer's device identifier (fraud monitoring)."
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/CreateCollection"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Final result already known (sandbox, or wait_for_result)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "response": {
                                            "type": "object",
                                            "properties": {
                                                "status": {
                                                    "type": "object",
                                                    "properties": {
                                                        "code": {
                                                            "type": "integer"
                                                        },
                                                        "message": {
                                                            "type": "string"
                                                        }
                                                    }
                                                },
                                                "records": {
                                                    "type": "object",
                                                    "properties": {
                                                        "code": {
                                                            "type": "string",
                                                            "example": "collection_initiated"
                                                        },
                                                        "trx_reference": {
                                                            "type": "string"
                                                        },
                                                        "reference": {
                                                            "type": "string"
                                                        },
                                                        "status": {
                                                            "$ref": "#/components/schemas/Status"
                                                        },
                                                        "mode": {
                                                            "type": "string"
                                                        },
                                                        "provider": {
                                                            "type": "string",
                                                            "enum": [
                                                                "mtn",
                                                                "airtel"
                                                            ]
                                                        },
                                                        "channel": {
                                                            "type": "string",
                                                            "example": "direct_api"
                                                        },
                                                        "payer_phone": {
                                                            "type": "string",
                                                            "example": "+260961***567"
                                                        },
                                                        "amount": {
                                                            "type": "string",
                                                            "example": "250.00000000"
                                                        },
                                                        "currency": {
                                                            "type": "string",
                                                            "example": "ZMW"
                                                        },
                                                        "payment_method": {
                                                            "type": "string"
                                                        },
                                                        "description": {
                                                            "type": "string"
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "message": {
                                                            "type": "string"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "202": {
                        "description": "Prompt sent; the result goes to callback_url",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "response": {
                                            "type": "object",
                                            "properties": {
                                                "status": {
                                                    "type": "object",
                                                    "properties": {
                                                        "code": {
                                                            "type": "integer"
                                                        },
                                                        "message": {
                                                            "type": "string"
                                                        }
                                                    }
                                                },
                                                "records": {
                                                    "type": "object",
                                                    "properties": {
                                                        "code": {
                                                            "type": "string",
                                                            "example": "collection_initiated"
                                                        },
                                                        "trx_reference": {
                                                            "type": "string"
                                                        },
                                                        "reference": {
                                                            "type": "string"
                                                        },
                                                        "status": {
                                                            "$ref": "#/components/schemas/Status"
                                                        },
                                                        "mode": {
                                                            "type": "string"
                                                        },
                                                        "provider": {
                                                            "type": "string",
                                                            "enum": [
                                                                "mtn",
                                                                "airtel"
                                                            ]
                                                        },
                                                        "channel": {
                                                            "type": "string",
                                                            "example": "direct_api"
                                                        },
                                                        "payer_phone": {
                                                            "type": "string",
                                                            "example": "+260961***567"
                                                        },
                                                        "amount": {
                                                            "type": "string",
                                                            "example": "250.00000000"
                                                        },
                                                        "currency": {
                                                            "type": "string",
                                                            "example": "ZMW"
                                                        },
                                                        "payment_method": {
                                                            "type": "string"
                                                        },
                                                        "description": {
                                                            "type": "string"
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "message": {
                                                            "type": "string"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "200": {
                        "description": "Same reference sent again: existing payment returned",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "response": {
                                            "type": "object",
                                            "properties": {
                                                "status": {
                                                    "type": "object",
                                                    "properties": {
                                                        "code": {
                                                            "type": "integer"
                                                        },
                                                        "message": {
                                                            "type": "string"
                                                        }
                                                    }
                                                },
                                                "records": {
                                                    "type": "object",
                                                    "properties": {
                                                        "code": {
                                                            "type": "string",
                                                            "example": "collection_replayed"
                                                        },
                                                        "trx_reference": {
                                                            "type": "string"
                                                        },
                                                        "reference": {
                                                            "type": "string"
                                                        },
                                                        "status": {
                                                            "$ref": "#/components/schemas/Status"
                                                        },
                                                        "mode": {
                                                            "type": "string"
                                                        },
                                                        "provider": {
                                                            "type": "string",
                                                            "enum": [
                                                                "mtn",
                                                                "airtel"
                                                            ]
                                                        },
                                                        "channel": {
                                                            "type": "string",
                                                            "example": "direct_api"
                                                        },
                                                        "payer_phone": {
                                                            "type": "string",
                                                            "example": "+260961***567"
                                                        },
                                                        "amount": {
                                                            "type": "string",
                                                            "example": "250.00000000"
                                                        },
                                                        "currency": {
                                                            "type": "string",
                                                            "example": "ZMW"
                                                        },
                                                        "payment_method": {
                                                            "type": "string"
                                                        },
                                                        "description": {
                                                            "type": "string"
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "message": {
                                                            "type": "string"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "repeat_payment_confirmation_required (or reference_conflict)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "response": {
                                            "type": "object",
                                            "properties": {
                                                "status": {
                                                    "type": "object",
                                                    "properties": {
                                                        "code": {
                                                            "type": "integer"
                                                        },
                                                        "message": {
                                                            "type": "string"
                                                        }
                                                    }
                                                },
                                                "records": {
                                                    "type": "object",
                                                    "properties": {
                                                        "code": {
                                                            "type": "string",
                                                            "example": "repeat_payment_confirmation_required"
                                                        },
                                                        "repeat_confirmation_token": {
                                                            "type": "string",
                                                            "format": "uuid"
                                                        },
                                                        "expires_in": {
                                                            "type": "integer",
                                                            "example": 300
                                                        },
                                                        "code_sent_to": {
                                                            "type": "object",
                                                            "properties": {
                                                                "sms": {
                                                                    "type": "string"
                                                                },
                                                                "email": {
                                                                    "type": "string"
                                                                }
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Invalid token or signature",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "validation_error, provider_unavailable or repeat_confirmation_invalid",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "502": {
                        "description": "provider_request_failed: safe to retry with a new reference",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v1/collections/{reference}": {
            "get": {
                "tags": [
                    "Mobile money (no redirect)"
                ],
                "summary": "Status of a collection (checks the provider if still pending)",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "reference",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "maxLength": 100
                        }
                    },
                    {
                        "name": "mode",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "sandbox",
                                "live"
                            ]
                        }
                    },
                    {
                        "$ref": "#/components/parameters/Timestamp"
                    },
                    {
                        "$ref": "#/components/parameters/Nonce"
                    },
                    {
                        "$ref": "#/components/parameters/Signature"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Status retrieved",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "response": {
                                            "type": "object",
                                            "properties": {
                                                "status": {
                                                    "type": "object",
                                                    "properties": {
                                                        "code": {
                                                            "type": "integer"
                                                        },
                                                        "message": {
                                                            "type": "string"
                                                        }
                                                    }
                                                },
                                                "records": {
                                                    "type": "object",
                                                    "properties": {
                                                        "code": {
                                                            "type": "string",
                                                            "example": "transaction_status_retrieved"
                                                        },
                                                        "trx_reference": {
                                                            "type": "string"
                                                        },
                                                        "reference": {
                                                            "type": "string"
                                                        },
                                                        "status": {
                                                            "$ref": "#/components/schemas/Status"
                                                        },
                                                        "mode": {
                                                            "type": "string"
                                                        },
                                                        "provider": {
                                                            "type": "string",
                                                            "enum": [
                                                                "mtn",
                                                                "airtel"
                                                            ]
                                                        },
                                                        "channel": {
                                                            "type": "string",
                                                            "example": "direct_api"
                                                        },
                                                        "payer_phone": {
                                                            "type": "string",
                                                            "example": "+260961***567"
                                                        },
                                                        "amount": {
                                                            "type": "string",
                                                            "example": "250.00000000"
                                                        },
                                                        "currency": {
                                                            "type": "string",
                                                            "example": "ZMW"
                                                        },
                                                        "payment_method": {
                                                            "type": "string"
                                                        },
                                                        "description": {
                                                            "type": "string"
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "updated_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "message": {
                                                            "type": "string"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Invalid token or signature",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "No collection with this reference",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v1/transactions": {
            "get": {
                "tags": [
                    "Transactions"
                ],
                "summary": "List your transactions",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "mode",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "sandbox",
                                "live"
                            ]
                        }
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "schema": {
                            "$ref": "#/components/schemas/Status"
                        }
                    },
                    {
                        "name": "provider",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "mtn",
                                "airtel"
                            ]
                        }
                    },
                    {
                        "name": "reference",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "maxLength": 100
                        }
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "format": "date"
                        }
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "format": "date"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "minimum": 1
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 100
                        }
                    },
                    {
                        "$ref": "#/components/parameters/Timestamp"
                    },
                    {
                        "$ref": "#/components/parameters/Nonce"
                    },
                    {
                        "$ref": "#/components/parameters/Signature"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Transactions",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "response": {
                                            "type": "object",
                                            "properties": {
                                                "status": {
                                                    "type": "object",
                                                    "properties": {
                                                        "code": {
                                                            "type": "integer"
                                                        },
                                                        "message": {
                                                            "type": "string"
                                                        }
                                                    }
                                                },
                                                "records": {
                                                    "type": "object",
                                                    "properties": {
                                                        "code": {
                                                            "type": "string",
                                                            "example": "transactions_retrieved"
                                                        },
                                                        "transactions": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "trx_reference": {
                                                                        "type": "string"
                                                                    },
                                                                    "reference": {
                                                                        "type": "string"
                                                                    },
                                                                    "status": {
                                                                        "$ref": "#/components/schemas/Status"
                                                                    },
                                                                    "mode": {
                                                                        "type": "string"
                                                                    },
                                                                    "provider": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "mtn",
                                                                            "airtel"
                                                                        ]
                                                                    },
                                                                    "channel": {
                                                                        "type": "string",
                                                                        "example": "direct_api"
                                                                    },
                                                                    "payer_phone": {
                                                                        "type": "string",
                                                                        "example": "+260961***567"
                                                                    },
                                                                    "amount": {
                                                                        "type": "string",
                                                                        "example": "250.00000000"
                                                                    },
                                                                    "currency": {
                                                                        "type": "string",
                                                                        "example": "ZMW"
                                                                    },
                                                                    "payment_method": {
                                                                        "type": "string"
                                                                    },
                                                                    "description": {
                                                                        "type": "string"
                                                                    },
                                                                    "created_at": {
                                                                        "type": "string",
                                                                        "format": "date-time"
                                                                    },
                                                                    "updated_at": {
                                                                        "type": "string",
                                                                        "format": "date-time"
                                                                    },
                                                                    "message": {
                                                                        "type": "string"
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "pagination": {
                                                            "type": "object",
                                                            "properties": {
                                                                "page": {
                                                                    "type": "integer"
                                                                },
                                                                "per_page": {
                                                                    "type": "integer"
                                                                },
                                                                "total": {
                                                                    "type": "integer"
                                                                },
                                                                "last_page": {
                                                                    "type": "integer"
                                                                }
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Invalid token or signature",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "validation_error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "securitySchemes": {
            "bearerAuth": {
                "type": "http",
                "scheme": "bearer",
                "bearerFormat": "JWT",
                "description": "Access token from POST /v1/auth/token. Every call also needs X-GatePay-Timestamp, X-GatePay-Nonce and X-GatePay-Signature."
            }
        },
        "parameters": {
            "ClientId": {
                "name": "X-Client-Id",
                "in": "header",
                "required": true,
                "schema": {
                    "type": "string",
                    "example": "ci_test_..."
                }
            },
            "Timestamp": {
                "name": "X-GatePay-Timestamp",
                "in": "header",
                "required": true,
                "schema": {
                    "type": "string",
                    "example": "1763380000"
                },
                "description": "Unix time in seconds; within 5 minutes of GatePay time."
            },
            "Nonce": {
                "name": "X-GatePay-Nonce",
                "in": "header",
                "required": true,
                "schema": {
                    "type": "string",
                    "pattern": "^[A-Za-z0-9_-]{16,64}$"
                },
                "description": "Random value, never reused."
            },
            "Signature": {
                "name": "X-GatePay-Signature",
                "in": "header",
                "required": true,
                "schema": {
                    "type": "string",
                    "pattern": "^[0-9a-f]{64}$"
                },
                "description": "hex HMAC-SHA256(client_secret, METHOD\\nPATH_AND_QUERY\\nTIMESTAMP\\nNONCE\\nhex(SHA-256(body)))."
            }
        },
        "schemas": {
            "Status": {
                "type": "string",
                "enum": [
                    "PENDING",
                    "SUCCESS",
                    "FAILED",
                    "CANCELLED",
                    "EXPIRED",
                    "REFUNDED"
                ]
            },
            "Amount": {
                "type": "string",
                "pattern": "^(?:0|[1-9]\\d{0,11})(?:\\.\\d{1,8})?$",
                "example": "250.00",
                "description": "Decimal string, greater than zero."
            },
            "CreatePayment": {
                "type": "object",
                "required": [
                    "mode",
                    "amount",
                    "currency",
                    "reference",
                    "success_url",
                    "cancel_url"
                ],
                "properties": {
                    "mode": {
                        "type": "string",
                        "enum": [
                            "sandbox",
                            "live"
                        ]
                    },
                    "amount": {
                        "$ref": "#/components/schemas/Amount"
                    },
                    "currency": {
                        "type": "string",
                        "minLength": 3,
                        "maxLength": 3,
                        "example": "ZMW"
                    },
                    "reference": {
                        "type": "string",
                        "maxLength": 100,
                        "example": "ORDER-1001"
                    },
                    "success_url": {
                        "type": "string",
                        "format": "uri"
                    },
                    "cancel_url": {
                        "type": "string",
                        "format": "uri"
                    },
                    "webhook_url": {
                        "type": "string",
                        "format": "uri"
                    },
                    "description": {
                        "type": "string",
                        "maxLength": 1000
                    },
                    "metadata": {
                        "type": "object",
                        "maxProperties": 20,
                        "additionalProperties": true
                    }
                }
            },
            "CreateCollection": {
                "type": "object",
                "required": [
                    "mode",
                    "provider",
                    "phone",
                    "amount",
                    "currency",
                    "reference",
                    "callback_url"
                ],
                "properties": {
                    "mode": {
                        "type": "string",
                        "enum": [
                            "sandbox",
                            "live"
                        ]
                    },
                    "provider": {
                        "type": "string",
                        "enum": [
                            "mtn",
                            "airtel"
                        ]
                    },
                    "phone": {
                        "type": "string",
                        "example": "+260961234567",
                        "description": "+260961234567, 260961234567 or 0961234567."
                    },
                    "amount": {
                        "$ref": "#/components/schemas/Amount"
                    },
                    "currency": {
                        "type": "string",
                        "minLength": 3,
                        "maxLength": 3,
                        "example": "ZMW"
                    },
                    "reference": {
                        "type": "string",
                        "maxLength": 100,
                        "example": "TRIP-10482"
                    },
                    "callback_url": {
                        "type": "string",
                        "format": "uri",
                        "description": "Must be HTTPS in live mode."
                    },
                    "description": {
                        "type": "string",
                        "maxLength": 160
                    },
                    "metadata": {
                        "type": "object",
                        "maxProperties": 20,
                        "additionalProperties": true
                    },
                    "wait_for_result": {
                        "type": "boolean",
                        "default": false
                    },
                    "customer_email": {
                        "type": "string",
                        "format": "email",
                        "description": "Also receives a repeat-payment confirmation code."
                    },
                    "repeat_confirmation_token": {
                        "type": "string",
                        "format": "uuid",
                        "description": "From a 409 repeat_payment_confirmation_required response."
                    },
                    "repeat_confirmation_code": {
                        "type": "string",
                        "pattern": "^\\d{6}$",
                        "description": "The code the customer received."
                    }
                }
            },
            "Error": {
                "type": "object",
                "properties": {
                    "response": {
                        "type": "object",
                        "properties": {
                            "status": {
                                "type": "object",
                                "properties": {
                                    "code": {
                                        "type": "integer"
                                    },
                                    "message": {
                                        "type": "string"
                                    }
                                }
                            },
                            "records": {
                                "type": "object",
                                "properties": {
                                    "code": {
                                        "type": "string",
                                        "example": "validation_error"
                                    },
                                    "errors": {
                                        "type": "object",
                                        "additionalProperties": {
                                            "type": "array",
                                            "items": {
                                                "type": "string"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}