> ## 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.

# Quickstart

> Get your WayPay account, API key, and make your first API call

## Create your WayPay account

To use the WayPay Merchant APIs, first create an account:

* Go to: [https://portal.dev.waypay.live](https://portal.dev.waypay.live)
* Click Sign Up and complete the registration form (business name, contact, email, phone).
* Verify your email address via the link sent to your inbox.
* Provide required business details and documents for compliance (KYC/KYB).
* Submit for review and wait for approval. You'll be notified once your account is active.

<Note>
  Your API access becomes available only after your account is approved and
  active. Approval timelines vary based on compliance review completeness.
</Note>

## Get your API key

Once approved:

* Sign in to the merchant portal.
* Locate your API key in the dashboard.
* Copy it securely. Never commit keys to source control.
* Use separate keys per environment and rotate them periodically.

All API requests must include this header:

```
SWICH-API-Key: YOUR_API_KEY
```

<Warning>
  Treat your API key like a password. Rotate it immediately if exposed.
</Warning>

## Understanding Test Mode

<Info>
  **Test Mode vs Production Mode**

  WayPay provides two environments to help you develop and test your integration safely:
</Info>

### Test Mode (Sandbox)

When using API keys that start with `pk_test_`, you are in **test mode**:

* ✅ **No real money is processed** - All transactions are simulated
* ✅ **Free unlimited testing** - Test as many transactions as you need
* ✅ **Instant processing** - No waiting for real bank confirmations
* ✅ **Same API behavior** - Test mode mirrors production functionality
* ✅ **Separate data** - Test transactions never affect production data

### Test Credentials

**Always use these standardized test credentials in sandbox mode:**

<CardGroup cols={2}>
  <Card title="Test Phone Number" icon="mobile">
    `03123456789`

    Use for all mobile wallet and customer phone fields
  </Card>

  <Card title="Test CNIC" icon="id-card">
    Full: `3520108345678`

    Last 6 digits: `345678`
  </Card>

  <Card title="Test OTP" icon="lock">
    `123456`

    Use when completing mobile wallet verification
  </Card>

  <Card title="Test Bank Account" icon="building-columns">
    IBAN: `PK36SCBL0000001123456702`

    Bank: Standard Chartered Bank

    Account Title: Test User
  </Card>
</CardGroup>

### Production Mode

When using API keys that start with `pk_live_`:

* ⚠️ **Real money is processed** - Actual charges and transfers occur
* 💳 **Real customer data required** - Use actual phone numbers, CNICs, bank accounts
* 🏦 **Real banking delays** - Transactions follow actual bank processing times
* 📊 **Affects live balances** - All transactions update production wallet balances

<Warning>
  **Never use test credentials (03123456789, 3520108345678) in production!** Always use real customer information when processing live transactions.
</Warning>

## Make your first test API call

Set your test API key in the terminal:

```bash theme={null}
export SWICH_API_KEY="pk_test_xxxxxxxxxxxxx"
```

### Example 1: Create a test checkout session

```bash theme={null}
curl -X POST "https://gateway.dev.waypay.live/Gateway/v1/Payment/initiate-checkout" \
  -H "Content-Type: application/json" \
  -H "SWICH-API-Key: $SWICH_API_KEY" \
  -d '{
    "amount": 1000,
    "currency": "PKR",
    "description": "Test Order 12345",
    "customerRef": {
      "name": "Test User",
      "email": "test@example.com",
      "cnic": "3520108345678",
      "phone": "03123456789"
    },
    "orderRef": { 
      "orderRef": "TEST-ORD-12345" 
    },
    "callbackUrl": "https://merchant.example.com/webhook/payment",
    "signature": "a1b2c3d4e5f6789012345678abcdef12"
  }'
```

You should receive a response with `paymentIntentId` and `checkoutUrl`:

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

Redirect your customer to the `checkoutUrl` to complete the test payment.

### Example 2: Test mobile wallet deposit

```bash theme={null}
curl -X POST "https://gateway.dev.waypay.live/Gateway/v1/Payment/deposit" \
  -H "Content-Type: application/json" \
  -H "SWICH-API-Key: $SWICH_API_KEY" \
  -d '{
    "mobileNumber": "03123456789",
    "amount": 1500,
    "walletProvider": 1,
    "currency": "PKR",
    "description": "Test Deposit",
    "intentType": "deposit",
    "customerRef": {
      "name": "Test User",
      "email": "test@example.com",
      "cnic": "3520108345678",
      "phone": "03123456789"
    },
    "orderRef": {
      "orderRef": "TEST-DEP-456"
    },
    "signature": "b2c3d4e5f6789012345678abcdef123"
  }'
```

**Expected Response:**

```json theme={null}
{
  "paymentIntentId": "770e8400-e29b-41d4-a716-446655440000",
  "amount": 1500,
  "currency": "PKR",
  "merchantReference": "TEST-DEP-456",
  "walletChargeInfo": {
    "provider": "JazzCash",
    "status": "Pending",
    "transactionReference": "JC20251213123456",
    "message": "OTP sent to customer",
    "isSuccess": true
  }
}
```

<Info>
  In test mode, use OTP `123456` to complete the mobile wallet verification.
</Info>

### Example 3: Test bank withdrawal/payout

```bash theme={null}
curl -X POST "https://gateway.dev.waypay.live/Gateway/v1/Payment/withdraw" \
  -H "Content-Type: application/json" \
  -H "SWICH-API-Key: $SWICH_API_KEY" \
  -d '{
    "amount": 5000,
    "currency": "PKR",
    "description": "Test Payout",
    "intentType": "withdrawal",
    "autoProcessPayout": true,
    "customerRef": {
      "name": "Test User",
      "email": "test@example.com",
      "cnic": "3520108345678",
      "phone": "03123456789",
      "bankAccountNumber": "PK36SCBL0000001123456702",
      "bankName": "Standard Chartered Bank",
      "accountTitle": "Test User"
    },
    "orderRef": {
      "orderRef": "TEST-WD-789"
    },
    "signature": "c3d4e5f6789012345678abcdef12345"
  }'
```

**Expected Response:**

```json theme={null}
{
  "paymentIntentId": "880e8400-e29b-41d4-a716-446655440000",
  "amount": 5000,
  "currency": "PKR",
  "merchantReference": "TEST-WD-789",
  "payoutInfo": {
    "status": "Processing",
    "provider": "Bank Transfer",
    "transactionReference": "WD20251213123456",
    "message": "Payout initiated successfully",
    "isSuccess": true,
    "errorDetails": null,
    "estimatedCompletionTime": "2025-12-14T10:00:00Z",
    "customerBankName": "Standard Chartered Bank",
    "customerAccountNumber": "PK36SCBL0000001123456702"
  }
}
```

## Additional Test Examples

### Check test wallet balance

```bash theme={null}
curl -X POST "https://gateway.dev.waypay.live/Gateway/v1/Account/query-balance" \
  -H "SWICH-API-Key: $SWICH_API_KEY"
```

### Get test transaction details

```bash theme={null}
curl -X GET "https://gateway.dev.waypay.live/Gateway/v1/Transaction/by-ref/TEST-ORD-12345" \
  -H "SWICH-API-Key: $SWICH_API_KEY"
```

### Issue a test refund

```bash theme={null}
curl -X POST "https://gateway.dev.waypay.live/Gateway/v1/Refunds" \
  -H "Content-Type: application/json" \
  -H "SWICH-API-Key: $SWICH_API_KEY" \
  -d '{
    "trxnRef": "TXN20251212123456",
    "amount": 500,
    "reason": "Test refund - customer return",
    "signature": "d4e5f6789012345678abcdef1234567"
  }'
```

<Note>
  **About Signatures in Examples**

  The `signature` field values shown in the examples above (e.g., `a1b2c3d4e5f6789012345678abcdef12`) are placeholders. In production, you must generate valid signatures using your secret key.

  See the [Signature Generation Guide](/signature-guide) for step-by-step instructions on how to generate signatures in C#, Node.js, Python, PHP, and Java.
</Note>

## Going Live Checklist

Before switching to production mode:

* ✅ Test all payment flows thoroughly in sandbox
* ✅ Implement proper error handling for all endpoints
* ✅ Set up and test webhook endpoints
* ✅ Test transaction status polling/verification
* ✅ Implement idempotency for all payment requests
* ✅ Set up proper logging and monitoring
* ✅ Review and implement security best practices
* ✅ Validate all required field formats (CNIC, phone, bank account)
* ✅ Complete KYC/KYB verification
* ✅ Obtain production API key (`pk_live_`)
* ✅ Update environment variables with production key
* ✅ **Switch to using real customer data** (phone, CNIC, bank accounts)
* ✅ Test a small transaction in production
* ✅ Monitor first few production transactions closely

<Warning>
  **Critical Reminders for Production:**

  * Real money will be processed
  * Use actual customer phone numbers (format: `^(\+92|0)?3\d{9}$`)
  * Use valid CNICs (13 digits: `^\d{13}$`)
  * Validate bank account details before withdrawals
  * Never use test credentials (03123456789, 3520108345678)
  * Keep production API keys secure
</Warning>

## Troubleshooting

### 401 Unauthorized

Ensure the header is present and correct:

```bash theme={null}
-H "SWICH-API-Key: $SWICH_API_KEY"
```

**Common issues:**

* Missing `SWICH-API-Key` header
* Incorrect API key
* Using test key in production or vice versa
* API key has been revoked

### 400 Bad Request

Check your payload fields and formats:

* `description` must be 1-200 alphanumeric characters and spaces
* `amount` must be greater than 10
* `currency` must be exactly 3 characters (e.g., "PKR")
* Required fields are present (name, email, cnic, phone)
* In test mode, use correct test credentials
* Phone must match pattern: `^(\+92|0)?3\d{9}$`
* CNIC must be 13 digits: `^\d{13}$`

### 422 Validation Error

Your request passed basic validation but failed business logic:

* Insufficient balance
* Invalid mobile number format (must be `03123456789` in test mode)
* Transaction already refunded
* CNIC format incorrect (must be `3520108345678` in test mode)
* Bank account number length invalid (10-24 characters)
* Email format invalid

<Note>
  See the full API reference and schema at the [API Reference](/api-reference/introduction), and detailed endpoint examples under API Reference → Endpoints.
</Note>

## Next steps

<CardGroup cols={2}>
  <Card title="API reference" icon="code" href="/api-reference/introduction">
    Explore endpoints, payloads, and examples powered by OpenAPI.
  </Card>

  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    Learn about API key management and security best practices.
  </Card>

  <Card title="Payment Endpoints" icon="credit-card" href="/api-reference/endpoints/payment-initiate">
    Deep dive into payment processing options.
  </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>
</CardGroup>

<Note>Need help? Contact [support@waypay.live](mailto:support@waypay.live) or check our documentation.</Note>