{
  "openapi": "3.0.0",
  "info": {
    "title": "Keshless Payment Integration API",
    "version": "1.0.0",
    "description": "Isolated developer sandbox. Simulated funds and SMS only. Test credentials never authorize live operations. Production activation requires separate live credentials.",
    "contact": {
      "name": "API Support",
      "email": "support@keshless.com"
    }
  },
  "servers": [
    {
      "url": "https://sandbox-api.keshless.com",
      "description": "Isolated sandbox — simulated money"
    }
  ],
  "paths": {
    "/api/auth/vendor/login": {
      "post": {
        "summary": "Login vendor or sub-user",
        "description": "Authenticate a vendor or vendor sub-user.\nProvide ONE of: email, phoneNumber, or username (plus password).\n- Vendors can login with email or phoneNumber\n- Sub-users can login with username, email, or phoneNumber\n",
        "tags": [
          "Vendor Authentication"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "password"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "description": "Vendor/sub-user email (provide one of email, phoneNumber, or username)",
                    "example": "vendor@example.com"
                  },
                  "phoneNumber": {
                    "type": "string",
                    "description": "Vendor/sub-user phone number",
                    "example": "+26876123456"
                  },
                  "username": {
                    "type": "string",
                    "description": "Sub-user username (at least 3 alphanumeric characters)",
                    "example": "cashier01"
                  },
                  "password": {
                    "type": "string",
                    "description": "Password or first-login PIN"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Login successful (returns vendor or sub-user based on credentials)"
          },
          "401": {
            "description": "Invalid credentials"
          },
          "403": {
            "description": "Account deactivated"
          }
        },
        "parameters": []
      }
    },
    "/api/auth/vendor/refresh-token": {
      "post": {
        "summary": "Refresh access token",
        "tags": [
          "Vendor Authentication"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "refreshToken"
                ],
                "properties": {
                  "refreshToken": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Token refreshed successfully"
          },
          "401": {
            "description": "Unauthorized"
          }
        },
        "parameters": []
      }
    },
    "/api/integrations": {
      "get": {
        "summary": "List all API keys for a vendor",
        "tags": [
          "Integrations"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "in": "query",
            "name": "vendorId",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of API keys"
          },
          "401": {
            "description": "Unauthorized"
          }
        }
      },
      "post": {
        "summary": "Create a new integration API key",
        "tags": [
          "Integrations"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "description": "Create an API key for server-to-server integration. Only admins or vendor owners can create keys.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "vendorId",
                  "appName"
                ],
                "properties": {
                  "vendorId": {
                    "type": "string",
                    "example": "60d5ec49f1b2c72b8c8e4f1a"
                  },
                  "appName": {
                    "type": "string",
                    "enum": [
                      "parkmate",
                      "tickets",
                      "custom"
                    ],
                    "example": "parkmate"
                  },
                  "expiresAt": {
                    "type": "string",
                    "format": "date-time",
                    "description": "Optional expiration date (ISO 8601)"
                  },
                  "ipWhitelist": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Optional list of allowed IP addresses"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "API key created successfully. Save the key - it will not be shown again!"
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden - insufficient permissions"
          }
        },
        "parameters": []
      }
    },
    "/api/integrations/{id}": {
      "get": {
        "summary": "Get a specific API key by ID",
        "tags": [
          "Integrations"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "vendorId",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "API key details"
          },
          "404": {
            "description": "API key not found"
          }
        }
      },
      "delete": {
        "summary": "Revoke an API key",
        "tags": [
          "Integrations"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "vendorId",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "API key revoked successfully"
          },
          "404": {
            "description": "API key not found"
          }
        }
      }
    },
    "/api/integrations/{id}/rotate": {
      "post": {
        "summary": "Rotate an API key (revoke old, create new)",
        "tags": [
          "Integrations"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "vendorId",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "API key rotated successfully. Save the new key - it will not be shown again!"
          },
          "404": {
            "description": "API key not found"
          }
        }
      }
    },
    "/api/integration/payment": {
      "post": {
        "summary": "Accept a merchant payment with durable idempotency",
        "tags": [
          "Payment Partners"
        ],
        "security": [
          {
            "ApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 8,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "description": "Use the same key for retries of one logical payment or refund. New confirmed-failed attempts need a new key."
          }
        ],
        "description": "All current calls use the sandbox. Identical retries return the committed outcome; changed request details under the same key return 409. Every supplied PIN is verified.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "amount"
                ],
                "additionalProperties": false,
                "oneOf": [
                  {
                    "required": [
                      "cardNumber"
                    ]
                  },
                  {
                    "required": [
                      "userId"
                    ]
                  }
                ],
                "properties": {
                  "amount": {
                    "type": "number",
                    "minimum": 0,
                    "exclusiveMinimum": true,
                    "maximum": 1000000,
                    "multipleOf": 0.01
                  },
                  "cardNumber": {
                    "type": "string",
                    "pattern": "^[A-Z0-9]{8}$"
                  },
                  "userId": {
                    "type": "string"
                  },
                  "pin": {
                    "type": "string",
                    "pattern": "^[0-9]{4}$",
                    "description": "Required at E50 and whenever PIN-less limits require it"
                  },
                  "description": {
                    "type": "string",
                    "maxLength": 200
                  },
                  "clientReference": {
                    "type": "string",
                    "maxLength": 128
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerOutcomeResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, expired, revoked or IP-restricted merchant key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Incorrect PIN, permission denied or sandbox disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Merchant resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Idempotency conflict or request still processing",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "423": {
            "description": "Wallet PIN is temporarily locked",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate or payment concurrency limit reached; respect Retry-After when present",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Dependency failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Required transaction verification is unavailable; check saved status before retrying",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/integration/balance": {
      "get": {
        "summary": "Get vendor balance via integration",
        "tags": [
          "Integrations"
        ],
        "security": [
          {
            "ApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Vendor balance"
          },
          "401": {
            "description": "Invalid API key"
          }
        },
        "parameters": []
      }
    },
    "/api/integration/transactions": {
      "get": {
        "summary": "Get vendor transactions via integration",
        "tags": [
          "Integrations"
        ],
        "security": [
          {
            "ApiKey": []
          }
        ],
        "parameters": [
          {
            "in": "query",
            "name": "startDate",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "in": "query",
            "name": "endDate",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "in": "query",
            "name": "type",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "default": 50,
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "in": "query",
            "name": "offset",
            "description": "Number of merchant transactions to skip",
            "schema": {
              "type": "integer",
              "default": 0,
              "minimum": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of transactions"
          },
          "401": {
            "description": "Invalid API key"
          }
        }
      }
    },
    "/api/integration/payments/{reference}": {
      "get": {
        "summary": "Retrieve merchant payment or refund outcome",
        "tags": [
          "Payment Partners"
        ],
        "security": [
          {
            "ApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerOutcomeResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, expired, revoked or IP-restricted merchant key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Incorrect PIN, permission denied or sandbox disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Merchant resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Idempotency conflict or request still processing",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate or payment concurrency limit reached; respect Retry-After when present",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Dependency failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "reference",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/api/integration/payments/by-key/{key}": {
      "get": {
        "summary": "Find a payment using the original idempotency key",
        "tags": [
          "Payment Partners"
        ],
        "security": [
          {
            "ApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerOutcomeResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, expired, revoked or IP-restricted merchant key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Incorrect PIN, permission denied or sandbox disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Merchant resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Idempotency conflict or request still processing",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate or payment concurrency limit reached; respect Retry-After when present",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Dependency failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/api/integration/payments/{reference}/refund": {
      "post": {
        "summary": "Refund the full purchase amount once",
        "tags": [
          "Payment Partners"
        ],
        "security": [
          {
            "ApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerOutcomeResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, expired, revoked or IP-restricted merchant key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Incorrect PIN, permission denied or sandbox disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Merchant resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Idempotency conflict or request still processing",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate or payment concurrency limit reached; respect Retry-After when present",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Dependency failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Required transaction verification is unavailable; check saved status before retrying",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 8,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "description": "Use the same key for retries of one logical payment or refund. New confirmed-failed attempts need a new key."
          },
          {
            "name": "reference",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "description": "Refunds the purchase amount only; original platform fees are retained and original payment commission is reversed. Restricted wallet funds remain restricted. Partial refunds are not supported.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "reason"
                ],
                "additionalProperties": false,
                "properties": {
                  "reason": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/integration/webhook": {
      "get": {
        "summary": "Read webhook settings without revealing the signing secret",
        "tags": [
          "Payment Partners"
        ],
        "security": [
          {
            "ApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerWebhookResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, expired, revoked or IP-restricted merchant key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Incorrect PIN, permission denied or sandbox disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Merchant resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Idempotency conflict or request still processing",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate or payment concurrency limit reached; respect Retry-After when present",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Dependency failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": []
      },
      "put": {
        "summary": "Configure an HTTPS webhook and rotate its signing secret",
        "tags": [
          "Payment Partners"
        ],
        "security": [
          {
            "ApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerWebhookResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, expired, revoked or IP-restricted merchant key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Incorrect PIN, permission denied or sandbox disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Merchant resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Idempotency conflict or request still processing",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate or payment concurrency limit reached; respect Retry-After when present",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Dependency failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "url"
                ],
                "additionalProperties": false,
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "maxLength": 2000
                  }
                }
              }
            }
          }
        },
        "parameters": []
      },
      "delete": {
        "summary": "Stop queuing new webhook events",
        "tags": [
          "Payment Partners"
        ],
        "security": [
          {
            "ApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerWebhookResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, expired, revoked or IP-restricted merchant key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Incorrect PIN, permission denied or sandbox disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Merchant resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Idempotency conflict or request still processing",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate or payment concurrency limit reached; respect Retry-After when present",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Dependency failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": []
      }
    },
    "/api/integration/webhook/events": {
      "get": {
        "summary": "List delivery outcomes and failures",
        "tags": [
          "Payment Partners"
        ],
        "security": [
          {
            "ApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerWebhookEventsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, expired, revoked or IP-restricted merchant key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Incorrect PIN, permission denied or sandbox disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Merchant resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Idempotency conflict or request still processing",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate or payment concurrency limit reached; respect Retry-After when present",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Dependency failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "in": "query",
            "name": "offset",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ]
      }
    },
    "/api/integration/webhook/events/{id}/retry": {
      "post": {
        "summary": "Retry a failed webhook event",
        "tags": [
          "Payment Partners"
        ],
        "security": [
          {
            "ApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, expired, revoked or IP-restricted merchant key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Incorrect PIN, permission denied or sandbox disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Merchant resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Idempotency conflict or request still processing",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate or payment concurrency limit reached; respect Retry-After when present",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Dependency failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/api/integration/sandbox/fixtures": {
      "post": {
        "summary": "Provision isolated sandbox test customers and cards",
        "tags": [
          "Payment Partners"
        ],
        "security": [
          {
            "ApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerFixturesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, expired, revoked or IP-restricted merchant key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Incorrect PIN, permission denied or sandbox disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Merchant resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Idempotency conflict or request still processing",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate or payment concurrency limit reached; respect Retry-After when present",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Dependency failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "description": "Enabled only on the explicitly configured Keshless dev database. Never available during production cutover.",
        "parameters": []
      }
    },
    "/api/integration/sandbox/migration-rehearsal": {
      "post": {
        "summary": "Rehearse merchant credential and replay-history portability",
        "tags": [
          "Payment Partners"
        ],
        "security": [
          {
            "ApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerMigrationResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, expired, revoked or IP-restricted merchant key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Incorrect PIN, permission denied or sandbox disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Merchant resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Idempotency conflict or request still processing",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate or payment concurrency limit reached; respect Retry-After when present",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Dependency failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "description": "Enabled only on the explicitly configured Keshless dev database. Never available during production cutover.",
        "parameters": []
      }
    },
    "/api/integration/sms": {
      "post": {
        "summary": "Send SMS via the centralized Keshless gateway",
        "description": "Send an SMS through the main Keshless API's SMS facade, picking up\nthe active provider (MTN SMPP or YeboLink) and shared credit pool.\nUsed by partner Keshless products (tickets, travels) so they don't\neach have to wire their own provider plumbing.\n",
        "tags": [
          "Integrations"
        ],
        "security": [
          {
            "ApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "to",
                  "message"
                ],
                "properties": {
                  "to": {
                    "type": "string",
                    "description": "E.164 phone number",
                    "example": "+26878422613"
                  },
                  "message": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 1000,
                    "example": "Your ticket TKT-123 is confirmed."
                  },
                  "senderId": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 11,
                    "description": "Optional sender ID; omit to use the configured gateway sender"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SMS dispatched to the gateway"
          },
          "401": {
            "description": "Invalid API key"
          },
          "502": {
            "description": "SMS gateway rejected the message"
          }
        },
        "parameters": []
      }
    },
    "/api/integration/sandbox/messages": {
      "get": {
        "summary": "Read this merchant’s captured SMS messages",
        "security": [
          {
            "ApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Sandbox operation result in the normal API response envelope"
          }
        }
      }
    },
    "/api/integration/sandbox/funds": {
      "post": {
        "summary": "Add simulated funds to this merchant or one of its fixture customers",
        "security": [
          {
            "ApiKey": []
          }
        ],
        "parameters": [
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 8,
              "maxLength": 128
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "amount"
                ],
                "properties": {
                  "amount": {
                    "type": "number",
                    "minimum": 0.01,
                    "maximum": 5000
                  },
                  "customerId": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Sandbox operation result in the normal API response envelope"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "JWT Authorization header using the Bearer scheme. Example: \"Authorization: Bearer {token}\""
      },
      "ApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Vendor integration key for server-to-server payment requests. Keep this key on your server."
      }
    },
    "schemas": {
      "PartnerOutcomeResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ApiResponse"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/PartnerOutcome"
              }
            }
          }
        ]
      },
      "ApiResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "description": "Indicates if the request was successful"
          },
          "message": {
            "type": "string",
            "description": "Response message"
          },
          "data": {
            "type": "object",
            "description": "Response data (varies by endpoint)"
          },
          "error": {
            "type": "string",
            "description": "Error message (only present on errors)"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "description": "Response timestamp"
          },
          "path": {
            "type": "string",
            "description": "Request path"
          }
        },
        "required": [
          "success",
          "message",
          "timestamp",
          "path"
        ]
      },
      "PartnerOutcome": {
        "type": "object",
        "required": [
          "reference",
          "status",
          "amount",
          "currency"
        ],
        "properties": {
          "environment": {
            "type": "string",
            "enum": [
              "sandbox",
              "production"
            ]
          },
          "reference": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "PENDING",
              "COMPLETED",
              "FAILED",
              "REFUNDED"
            ]
          },
          "amount": {
            "type": "number"
          },
          "currency": {
            "type": "string",
            "enum": [
              "SZL"
            ]
          },
          "replayed": {
            "type": "boolean"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "customerId": {
            "type": "string"
          },
          "customerCharged": {
            "type": "number"
          },
          "merchantReceived": {
            "type": "number"
          },
          "userFee": {
            "type": "number"
          },
          "merchantFee": {
            "type": "number"
          },
          "clientReference": {
            "type": "string",
            "nullable": true
          },
          "walletTransactionId": {
            "type": "string"
          },
          "paymentReference": {
            "type": "string"
          },
          "refundReference": {
            "type": "string"
          },
          "feesRefunded": {
            "type": "boolean"
          },
          "failure": {
            "type": "object",
            "properties": {
              "message": {
                "type": "string"
              },
              "statusCode": {
                "type": "integer"
              }
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "message": {
            "type": "string",
            "description": "Error message"
          },
          "error": {
            "type": "string",
            "description": "Detailed error description"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "path": {
            "type": "string",
            "description": "Request path"
          }
        }
      },
      "PartnerWebhookResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ApiResponse"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "configured": {
                    "type": "boolean"
                  },
                  "url": {
                    "type": "string",
                    "format": "uri"
                  },
                  "signingSecret": {
                    "type": "string",
                    "description": "Shown only in the configuration response; never returned by GET"
                  },
                  "configuredAt": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "events": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        ]
      },
      "PartnerWebhookEventsResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ApiResponse"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "events": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "operationId": {
                          "type": "string"
                        },
                        "eventType": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "PENDING",
                            "DELIVERED",
                            "FAILED"
                          ]
                        },
                        "attempts": {
                          "type": "integer"
                        },
                        "lastError": {
                          "type": "string",
                          "nullable": true
                        },
                        "nextAttemptAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "createdAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "deliveredAt": {
                          "type": "string",
                          "format": "date-time",
                          "nullable": true
                        }
                      }
                    }
                  },
                  "pagination": {
                    "type": "object",
                    "properties": {
                      "limit": {
                        "type": "integer"
                      },
                      "offset": {
                        "type": "integer"
                      },
                      "total": {
                        "type": "integer"
                      },
                      "hasNext": {
                        "type": "boolean"
                      }
                    }
                  }
                }
              }
            }
          }
        ]
      },
      "PartnerFixturesResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ApiResponse"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "environment": {
                    "type": "string",
                    "enum": [
                      "sandbox"
                    ]
                  },
                  "merchantId": {
                    "type": "string"
                  },
                  "customers": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "scenario": {
                          "type": "string",
                          "enum": [
                            "verified",
                            "pin_required",
                            "insufficient_balance",
                            "unverified"
                          ]
                        },
                        "userId": {
                          "type": "string"
                        },
                        "cardNumber": {
                          "type": "string"
                        },
                        "pin": {
                          "type": "string"
                        },
                        "balance": {
                          "type": "number"
                        },
                        "currency": {
                          "type": "string",
                          "enum": [
                            "SZL"
                          ]
                        }
                      }
                    }
                  },
                  "webhookReceiverUrl": {
                    "type": "string",
                    "format": "uri"
                  }
                }
              }
            }
          }
        ]
      },
      "PartnerMigrationResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ApiResponse"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "passed": {
                    "type": "boolean"
                  },
                  "merchantIdPreserved": {
                    "type": "boolean"
                  },
                  "apiKeyPreserved": {
                    "type": "boolean"
                  },
                  "replayHistoryPreserved": {
                    "type": "boolean"
                  },
                  "sandboxWalletBalancesMigrated": {
                    "type": "boolean"
                  },
                  "productionChanged": {
                    "type": "boolean"
                  },
                  "merchantChangesRequired": {
                    "type": "boolean"
                  },
                  "webhookSecretPreserved": {
                    "type": "boolean",
                    "nullable": true
                  },
                  "operationsChecked": {
                    "type": "integer"
                  },
                  "scope": {
                    "type": "string"
                  },
                  "integrationBaseUrlBefore": {
                    "type": "string",
                    "format": "uri"
                  },
                  "integrationBaseUrlAfter": {
                    "type": "string",
                    "format": "uri"
                  }
                }
              }
            }
          }
        ]
      }
    }
  },
  "security": [],
  "tags": [
    {
      "name": "Vendor Authentication"
    },
    {
      "name": "Integrations"
    },
    {
      "name": "Payment Partners"
    }
  ]
}
