Skip to main content
This section documents the Waypay Gateway API using the bundled OpenAPI spec.

​
Overview

The Waypay Gateway lets merchants:
  • Initiate hosted checkout payment intents
  • Charge tokenized mobile wallets
  • Create and manage refunds
All requests must include your API key header: Swich-API-Key: sk_live_XXXX OpenAPI source: /docs/api-reference/openapi.json

​
Tags

Payments – Initiate payment intents
Wallet – Charge mobile wallets
Refunds – Create / cancel refunds
Authentication – API key requirements
Webhooks – (reserved for future events)

​
Quick Start

export SWICH_API_KEY="sk_live_XXXX"

curl -X POST "https://waypay-merchant-api.icydesert-41d42f7e.uaenorth.azurecontainerapps.io/Gateway/v1/Payment/initiate" \
  -H "Content-Type: application/json" \
  -H "Swich-API-Key: $SWICH_API_KEY" \
  -d '{
    "amount": 50000,
    "currency": "PKR",
    "description": "Order 12345",
    "customerRef": {
    "name": "Ayesha Khan",
    "email": "ayesha@example.com",
    "phone": "+923001234567"
    },
    "orderRef": { "orderRef": "ORD12345" },
    "successUrl": "https://merchant.example.com/checkout/success",
    "cancelUrl": "https://merchant.example.com/checkout/cancel"
  }'
Successful response returns paymentIntentId and checkoutUrl.

​
Authentication

The spec defines an API Key security scheme: 
"securitySchemes": {
  "SwichApiKey": {
    "type": "apiKey",
    "in": "header",
    "name": "Swich-API-Key"
  }
},
"security": [{ "SwichApiKey": [] }]
Send the header on every request.

​
Error Model

Errors use ErrorResponse (preferred) or legacy ProblemDetails. ErrorResponse example: 
{
  "code": "validation_error",
  "message": "description must match ^[A-Za-z0-9 ]{1,200}$",
  "details": {
    "field": "description",
    "issue": "invalid_format"
  }
}

​
Flow

  1. POST /Payment/initiate → get checkoutUrl
  2. Customer completes payment at hosted UI
  3. (Optional) Charge mobile wallet directly for tokenized flows
  4. (Optional) POST /Refunds to issue refund; cancel if still pending
Proceed to endpoint examples for concrete requests and responses.