> ## Documentation Index
> Fetch the complete documentation index at: https://docs.waypay.live/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Complete guide to the Waypay Gateway API

## Welcome to Waypay API

The Waypay Gateway API allows you to accept payments, process payouts, manage refunds, and handle settlements programmatically. Built on REST principles with predictable resource-oriented URLs, JSON responses, and standard HTTP response codes.

<Note>
  All API requests require authentication using your API key. See the [Authentication](/api-reference/authentication) section for details.
</Note>

## Base URL

```
https://gateway.dev.waypay.live/Gateway/v1
```

## Key Features

<CardGroup cols={2}>
  <Card title="Payment Processing" icon="credit-card">
    Accept payments via hosted checkout or custom integrations with support for cards and mobile wallets
  </Card>

  <Card title="Mobile Wallet Charging" icon="mobile">
    Directly charge JazzCash, Easypaisa mobile wallets
  </Card>

  <Card title="Deposits & Withdrawals" icon="money-bill-transfer">
    Create deposit orders to collect funds and withdrawal orders to disburse payments
  </Card>

  <Card title="Refund Management" icon="rotate-left">
    Process full or partial refunds with automated tracking
  </Card>

  <Card title="Settlement Control" icon="building-columns">
    Manage fund withdrawals with manual or automatic scheduling
  </Card>

  <Card title="Real-time Webhooks" icon="webhook">
    Receive instant notifications for transaction events
  </Card>
</CardGroup>

## API Capabilities

### Account Endpoints

* **Query Balance** - Retrieve wallet balance, pending amounts, and transaction counts

### Payment Endpoints

* **Initiate Checkout** - Create hosted payment sessions
* **Create Deposit** - Initiate mobile wallet charges for payment collection
* **Create Withdrawal** - Process payouts to customer bank accounts
* **Charge Mobile Wallet** - Direct mobile wallet charging with tokens
* **Get Token Info** - Retrieve payment token details

### Transaction Endpoints

* **Get by Reference** - Retrieve transaction by reference number
* **Get by ID** - Retrieve transaction by unique identifier

### Refund Endpoints

* **Create Refund** - Initiate full or partial refunds
* **Get Refund** - Retrieve refund details
* **Cancel Refund** - Cancel pending refunds

### Settlement Endpoints

* **Create Settlement** - Request fund withdrawal to bank or USDT
* **Get Settlement** - Retrieve specific settlement details
* **Configure Schedule** - Set up automatic settlements with customizable parameters
* **Get Schedule** - Retrieve current settlement schedule configuration

## Environments

Waypay provides separate environments for testing and production:

| Environment | Base URL                                     | API Key Prefix |
| ----------- | -------------------------------------------- | -------------- |
| Test        | `https://gateway.dev.waypay.live/Gateway/v1` | `pk_test_`     |
| Production  | `https://gateway.dev.waypay.live/Gateway/v1` | `pk_live_`     |

<Tip>
  Use test mode to integrate and test your application without processing real transactions.
</Tip>

## Test Mode / Sandbox

<Warning>
  **Important: Test Mode Information**

  When using test API keys (those starting with `pk_test_`), you are in **sandbox mode**. No real money is processed in test mode.
</Warning>

### Test Mode Features

* ✅ **No real money charged** - All transactions are simulated
* ✅ **Free to test** - Test as many transactions as you need
* ✅ **Same API behavior** - Test mode mirrors production functionality
* ✅ **Separate data** - Test data never affects production
* ✅ **Instant processing** - No waiting for bank confirmations

### Test Credentials

Use these standardized test credentials when testing in sandbox mode:

<AccordionGroup>
  <Accordion title="Test Mobile Number">
    **Phone Number:** `03123456789`

    Use this mobile number for:

    * Deposit orders
    * Mobile wallet charging
    * Customer phone field
    * Any mobile wallet transactions
  </Accordion>

  <Accordion title="Test CNIC">
    **CNIC:** `3520108345678`

    **Last 6 digits:** `345678`

    Use this CNIC for:

    * Customer CNIC field
    * Last 6 CNIC digits verification
    * Bank account validation
    * Withdrawal requests
  </Accordion>

  <Accordion title="Test OTP">
    **OTP Code:** `123456`

    When testing mobile wallet transactions, use this OTP to complete verification.
  </Accordion>

  <Accordion title="Test Bank Account">
    **Account Number:** `PK36SCBL0000001123456702`

    **Bank Name:** `Standard Chartered Bank`

    **Account Holder:** `Ahmed Ali`

    Use these for testing withdrawal/payout flows.
  </Accordion>
</AccordionGroup>

### Example Test Request

```bash theme={null}
curl --request POST \
  --url https://gateway.dev.waypay.live/Gateway/v1/Payment/deposit \
  --header 'SWICH-API-Key: pk_test_xxxxxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "mobileNumber": "03123456789",
    "amount": 1500,
    "walletProvider": 1,
    "currency": "PKR",
    "description": "Test Payment",
    "intentType": "deposit",
    "customerRef": {},
    "orderRef": {
      "orderRef": "TEST123456"
    }
  }'
```

### Switching to Production

When you're ready to go live:

1. ✅ Complete all testing in sandbox mode
2. ✅ Implement proper error handling
3. ✅ Set up webhook endpoints
4. ✅ Test all payment flows end-to-end
5. 🔄 **Switch to production API key** (starts with `pk_live_`)
6. 🔄 **Use real customer data** instead of test credentials
7. 🔄 **Real money will be processed**

<Warning>
  **Never use test credentials in production!** Always use real customer phone numbers, CNICs, and bank details when processing live transactions.
</Warning>

## Quick Start

Here's how to create your first test payment:

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://gateway.dev.waypay.live/Gateway/v1/Payment/initiate-checkout \
    --header 'SWICH-API-Key: pk_test_xxxxxxxxxxxxx' \
    --header 'Content-Type: application/json' \
    --data '{
      "amount": 1000,
      "currency": "PKR",
      "description": "Product Purchase",
      "customerRef": {},
      "orderRef": {
        "orderRef": "ORD123456"
      },
      "callbackUrl": "https://yoursite.com/payment/callback"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://gateway.dev.waypay.live/Gateway/v1/Payment/initiate-checkout',
    {
      method: 'POST',
      headers: {
        'SWICH-API-Key': process.env.WAYPAY_API_KEY, // pk_test_ for testing
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        amount: 1000,
        currency: 'PKR',
        description: 'Product Purchase',
        customerRef: {},
        orderRef: {
          orderRef: 'ORD123456'
        },
        callbackUrl: 'https://yoursite.com/payment/callback'
      })
    }
  );

  const data = await response.json();
  // Redirect customer to data.checkoutUrl
  ```

  ```python Python theme={null}
  import os
  import requests

  api_key = os.environ.get('WAYPAY_API_KEY')  # pk_test_ for testing

  response = requests.post(
      'https://gateway.dev.waypay.live/Gateway/v1/Payment/initiate-checkout',
      headers={
          'SWICH-API-Key': api_key,
          'Content-Type': 'application/json'
      },
      json={
          'amount': 1000,
          'currency': 'PKR',
          'description': 'Product Purchase',
          'customerRef': {},
          'orderRef': {
              'orderRef': 'ORD123456'
          },
          'callbackUrl': 'https://yoursite.com/payment/callback'
      }
  )

  data = response.json()
  # Redirect customer to data['checkoutUrl']
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "paymentIntentId": "550e8400-e29b-41d4-a716-446655440000",
  "checkoutUrl": "https://checkout.waypay.com/pay/abc123xyz",
  "expiresAt": "2025-12-12T12:00:00Z"
}
```

## Authentication

All API requests must include your API key in the `SWICH-API-Key` header:

```
SWICH-API-Key: pk_live_your_api_key
```

<Warning>
  Never share your API key or commit it to version control. Use environment variables to store your keys securely.
</Warning>

## Versioning

The API version is specified in the URL path. The current version is `v1`:

```
/Gateway/v1/Payment/initiate-checkout
```

We maintain backwards compatibility within major versions. Breaking changes will result in a new version number.

## Rate Limits

To ensure service stability, API requests are rate-limited:

* **Test Environment**: 100 requests per minute
* **Production Environment**: 1000 requests per minute

Rate limit information is included in response headers:

```
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1639564800
```

## Error Handling

Waypay uses conventional HTTP response codes:

| Status Code | Meaning                                 |
| ----------- | --------------------------------------- |
| 200-299     | Success                                 |
| 400         | Bad Request - Invalid parameters        |
| 401         | Unauthorized - Invalid API key          |
| 404         | Not Found - Resource doesn't exist      |
| 422         | Unprocessable Entity - Validation error |
| 429         | Too Many Requests - Rate limit exceeded |
| 500         | Internal Server Error                   |

### Error Response Format

```json theme={null}
{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "Invalid request parameters",
  "instance": "/Gateway/v1/Payment/initiate-checkout"
}
```

See [Error Codes](/api-reference/endpoints/errors) for detailed information.

## Supported Mobile Wallets

Waypay supports integration with Pakistan's leading mobile wallet providers:

| Provider  | Code | Status |
| --------- | ---- | ------ |
| JazzCash  | 1    | Active |
| Easypaisa | 2    | Active |

## Payment Flows

### 1. Hosted Checkout Flow

The simplest integration - redirect customers to Waypay's hosted checkout page:

1. Call `/Payment/initiate-checkout`
2. Redirect customer to returned `checkoutUrl`
3. Customer completes payment
4. Receive webhook notification
5. Customer redirected to your success/cancel URL

### 2. Deposit Flow (Direct Mobile Wallet)

Collect payments directly from mobile wallets:

1. Call `/Payment/deposit` with customer wallet details
2. Customer receives OTP on their mobile
3. Customer completes OTP verification
4. Receive webhook notification

### 3. Withdrawal Flow (Bank Payout)

Disburse funds to customer bank accounts:

1. Call `/Payment/withdraw` with bank details
2. System processes payout (auto or manual approval)
3. Funds transferred to customer bank
4. Receive webhook notification

## Idempotency

To safely retry requests without performing the same operation twice, include an idempotency key:

```
Idempotency-Key: unique-key-123
```

Waypay stores the result of the first request and returns it for subsequent requests with the same key (valid for 24 hours).

## Webhooks

Receive real-time notifications when events occur in your Waypay account:

* Payment completed
* Payment failed
* Deposit confirmed
* Withdrawal processed
* Refund processed
* Settlement completed

Configure webhook endpoints in your dashboard.

## Support

Need help? We're here for you:

* 📧 Email: [support@waypay.live](mailto:support@waypay.live)
* 💬 Live Chat: Available in your dashboard
* 📚 Documentation: [https://docs.waypay.live](https://docs.waypay.live)
* 🐛 Report Issues: [support@waypay.live](mailto:support@waypay.live)

## Next Steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    Learn how to authenticate your API requests
  </Card>

  <Card title="Account Balance" icon="wallet" href="/api-reference/endpoints/account-query-balance">
    Check your wallet balance and pending transactions
  </Card>

  <Card title="Payment Endpoints" icon="credit-card" href="/api-reference/endpoints/payment-initiate">
    Start accepting payments
  </Card>

  <Card title="Deposit Orders" icon="download" href="/api-reference/endpoints/payment-deposit">
    Collect payments from mobile wallets
  </Card>

  <Card title="Withdrawal Orders" icon="upload" href="/api-reference/endpoints/payment-withdraw">
    Process payouts to bank accounts
  </Card>

  <Card title="Webhooks" icon="webhook" href="/guides/webhooks">
    Set up real-time event notifications
  </Card>

  <Card title="Quickstart Guide" icon="rocket" href="/quickstart">
    Build your first integration
  </Card>
</CardGroup>