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

# Create Deposit Order

> Create a deposit order to collect payment from customer's mobile wallet

## Overview

This endpoint creates a deposit order that initiates a mobile wallet charge from your customer. Use this for collecting payments directly from mobile wallets like JazzCash, Easypaisa.

## Path Parameters

<ParamField path="version" type="string" required>
  API version (e.g., "1")
</ParamField>

## Request Body

<ParamField body="mobileNumber" type="string" required>
  Customer's mobile wallet number
</ParamField>

<ParamField body="amount" type="number" required>
  Deposit amount. Minimum depends on the wallet provider:

  * JazzCash: minimum 100
  * Easypaisa: minimum 200
</ParamField>

<ParamField body="walletProvider" type="integer">
  Mobile wallet provider code:

  * 1: JazzCash
  * 2: Easypaisa
</ParamField>

<ParamField body="paymentMethod" type="integer">
  Payment method (same as walletProvider):

  * 1: JazzCash
  * 2: Easypaisa
</ParamField>

<ParamField body="currency" type="string">
  Payment currency (e.g., "PKR")
</ParamField>

<ParamField body="description" type="string" required>
  Payment description (1-200 alphanumeric characters and spaces only)

  **Pattern:** `^[A-Za-z0-9 ]{1,200}$`
</ParamField>

<ParamField body="callbackUrl" type="string">
  Webhook URL on your server to receive real-time transaction status updates

  This should be a publicly accessible HTTPS endpoint in your merchant system that can receive POST requests from Waypay. When a transaction status changes, Waypay will send a webhook notification to this URL with the transaction details.

  **When to use this parameter:**

  * Use this parameter only if you need a **dynamic webhook URL** that varies per transaction (e.g., session-specific, order-specific URLs)
  * If your webhook URL is **static** (same for all transactions), configure it in your **Merchant Portal** instead. The system will automatically use the portal-configured URL when this parameter is not provided.

  **Maximum length:** 2048 characters

  **Required:** HTTPS URL that can accept POST requests

  **Example (Dynamic):** `https://yoursite.com/api/webhooks/deposit?order_id=12345`

  **Example (Static):** Configure `https://yoursite.com/api/webhooks/payment` in Merchant Portal and omit this parameter

  <Tip>
    **Best Practice:** Use the Merchant Portal for static webhook URLs. Use this parameter only when you need dynamic, per-transaction webhook URLs.
  </Tip>

  See the [Initiate Checkout](/api-reference/endpoints/payment-initiate#callback-url) documentation for complete webhook payload structure and implementation examples.
</ParamField>

<ParamField body="intentType" type="string">
  Payment intent type (e.g., "deposit")
</ParamField>

<ParamField body="customerRef" type="object">
  Customer information (optional object, all fields within are also optional)

  <Expandable title="properties">
    <ParamField body="name" type="string">
      Customer full name
    </ParamField>

    <ParamField body="email" type="string">
      Customer email address (must be valid email format)
    </ParamField>

    <ParamField body="cnic" type="string">
      Customer CNIC number - must be exactly 13 digits

      **Pattern:** `^\d{13}$`

      **Example:** `3520108345678`
    </ParamField>

    <ParamField body="phone" type="string">
      Customer phone number
    </ParamField>

    <ParamField body="shippingAddress" type="string">
      Optional shipping address
    </ParamField>

    <ParamField body="estimatedDays" type="string">
      Estimated delivery days
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="orderRef" type="object" required>
  Order information

  <Expandable title="properties">
    <ParamField body="orderRef" type="string" required>
      Order reference (alphanumeric characters)

      **Pattern:** `^[A-Za-z0-9]+$`
    </ParamField>

    <ParamField body="discount" type="string">
      Discount amount or percentage
    </ParamField>

    <ParamField body="tax" type="string">
      Tax amount or percentage
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="signature" type="string" required>
  Request signature for security verification

  A cryptographic signature generated using MD5 hash algorithm to ensure the integrity and authenticity of the request. The signature is calculated using all request parameters (excluding the signature field itself) combined with your merchant secret key.

  **Format:** 32-character lowercase hexadecimal string

  **Example:** `a1b2c3d4e5f6789012345678abcdef12`

  <Warning>
    Never expose your secret key in client-side code. Always generate signatures on your server.
  </Warning>

  **Learn how to generate signatures:** See the complete [Signature Generation Guide](/signature-guide) for step-by-step instructions and implementation examples in C#, Node.js, Python, PHP, and Java.
</ParamField>

## Response

<ResponseField name="paymentIntentId" type="uuid">
  Unique identifier for the payment intent
</ResponseField>

<ResponseField name="amount" type="number">
  Deposit amount
</ResponseField>

<ResponseField name="currency" type="string">
  Payment currency
</ResponseField>

<ResponseField name="merchantReference" type="string">
  Your merchant reference for this transaction
</ResponseField>

<ResponseField name="walletChargeInfo" type="object">
  Information about the wallet charge attempt

  <Expandable title="properties">
    <ResponseField name="provider" type="string">
      Wallet provider name (e.g., "JazzCash", "Easypaisa")
    </ResponseField>

    <ResponseField name="status" type="string">
      Charge status (e.g., "Pending", "Success", "Failed")
    </ResponseField>

    <ResponseField name="transactionReference" type="string">
      Provider's transaction reference number
    </ResponseField>

    <ResponseField name="message" type="string">
      Status message from the wallet provider
    </ResponseField>

    <ResponseField name="isSuccess" type="boolean">
      Whether the charge initiation was successful
    </ResponseField>

    <ResponseField name="errorDetails" type="string">
      Detailed error information if charge failed
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://gateway.dev.waypay.live/Gateway/v1/Payment/deposit \
    --header 'SWICH-API-Key: pk_test_xxxxxxxx' \
    --header 'Content-Type: application/json' \
    --data '{
      "mobileNumber": "03123456789",
      "amount": 1500,
      "walletProvider": 1,
      "paymentMethod": 1,
      "currency": "PKR",
      "description": "Product Purchase",
      "intentType": "deposit",
      "callbackUrl": "https://yoursite.com/payment/callback",
      "orderRef": {
        "orderRef": "ORD123456"
      },
      "signature": "a1b2c3d4e5f6789012345678abcdef12"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://gateway.dev.waypay.live/Gateway/v1/Payment/deposit',
    {
      method: 'POST',
      headers: {
        'SWICH-API-Key': 'pk_test_xxxxxxxx',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        mobileNumber: '03123456789',
        amount: 1500,
        walletProvider: 1,
        paymentMethod: 1,
        currency: 'PKR',
        description: 'Product Purchase',
        intentType: 'deposit',
        callbackUrl: 'https://yoursite.com/payment/callback',
        orderRef: {
          orderRef: 'ORD123456'
        },
        signature: 'a1b2c3d4e5f6789012345678abcdef12'
      })
    }
  );

  const data = await response.json();
  console.log('Payment Intent ID:', data.paymentIntentId);
  ```

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

  response = requests.post(
      'https://gateway.dev.waypay.live/Gateway/v1/Payment/deposit',
      headers={
          'SWICH-API-Key': 'pk_test_xxxxxxxx',
          'Content-Type': 'application/json'
      },
      json={
          'mobileNumber': '03123456789',
          'amount': 1500,
          'walletProvider': 1,
          'paymentMethod': 1,
          'currency': 'PKR',
          'description': 'Product Purchase',
          'intentType': 'deposit',
          'callbackUrl': 'https://yoursite.com/payment/callback',
          'orderRef': {
              'orderRef': 'ORD123456'
          },
          'signature': 'a1b2c3d4e5f6789012345678abcdef12'
      }
  )

  data = response.json()
  print(f"Charge Status: {data['walletChargeInfo']['status']}")
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "paymentIntentId": "770e8400-e29b-41d4-a716-446655440000",
    "amount": 1500,
    "currency": "PKR",
    "merchantReference": "ORD123456",
    "walletChargeInfo": {
      "provider": "JazzCash",
      "status": "Pending",
      "transactionReference": "JC20251213123456",
      "message": "OTP sent to customer",
      "isSuccess": true,
      "errorDetails": null
    }
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "Bad Request",
    "status": 400,
    "detail": "Invalid mobile number format or CNIC digits"
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "type": "https://tools.ietf.org/html/rfc7235#section-3.1",
    "title": "Unauthorized",
    "status": 401,
    "detail": "Invalid or missing API key"
  }
  ```

  ```json 422 Unprocessable Content theme={null}
  {
    "type": "https://tools.ietf.org/html/rfc4918#section-11.2",
    "title": "Unprocessable Content",
    "status": 422,
    "detail": "Wallet provider not available or insufficient customer wallet balance"
  }
  ```
</ResponseExample>

## Validation Rules

### CNIC Format

* Must be exactly 13 digits
* Pattern: `^\d{13}$`
* Example: `3520108345678`

### Order Reference

* Alphanumeric characters only
* Pattern: `^[A-Za-z0-9]+$`
* Example: `ORD123456`

### Description

* Length: 1-200 characters
* Pattern: `^[A-Za-z0-9 ]{1,200}$`
* Only alphanumeric characters and spaces allowed

## Wallet Provider Codes

| Provider  | Code | Status | Description                                 |
| --------- | ---- | ------ | ------------------------------------------- |
| JazzCash  | 1    | Active | Pakistan's leading mobile wallet service    |
| Easypaisa | 2    | Active | Popular mobile wallet and financial service |

<Note>
  The `paymentMethod` and `walletProvider` fields accept the same values. You can use either field to specify the payment method.
</Note>

## Payment Flow

1. **Create Deposit Order** - Call this endpoint with customer details
2. **Customer Receives OTP** - Mobile wallet provider sends OTP to customer's phone
3. **Customer Verification** - Customer enters OTP in their wallet app to approve
4. **Webhook Notification** - You receive webhook when payment is confirmed
5. **Transaction Complete** - Funds are added to your merchant wallet

<Info>
  In test mode, use OTP `123456` to complete wallet verification for testing purposes.
</Info>

## Best Practices

* **Validate Before Submission**: Always validate mobile number and CNIC format before making the request
* **Handle OTP Flow**: Implement proper UI/UX for customers to complete OTP verification
* **Monitor Status**: Poll the transaction status or use webhooks to get real-time updates
* **Error Handling**: Implement retry logic for temporary failures
* **Store Payment Intent ID**: Keep the `paymentIntentId` for reconciliation and support
* **Test Mode**: Use test credentials (`03123456789`) in sandbox environment
* **Production Mode**: Use real customer data when processing live transactions

## Common Error Scenarios

| Error                 | Cause                                  | Solution                              |
| --------------------- | -------------------------------------- | ------------------------------------- |
| Wallet not available  | Customer's wallet account inactive     | Ask customer to verify wallet account |
| Insufficient balance  | Customer wallet has insufficient funds | Customer needs to top up wallet       |
| Invalid mobile number | Number not registered with wallet      | Verify mobile number with customer    |
| OTP timeout           | Customer didn't complete verification  | Retry the deposit request             |

## Security Considerations

* Never store customer CNIC or sensitive information in plain text
* Use HTTPS for all API communications
* Validate customer identity before processing deposits
* Implement rate limiting to prevent abuse
* Monitor for suspicious transaction patterns
* Keep API keys secure and rotate regularly

## Testing

Use these test credentials in sandbox mode:

* **Mobile Number**: `03123456789`
* **CNIC**: `3520108345678`
* **OTP**: `123456`
* **Wallet Provider**: `1` (JazzCash) or `2` (Easypaisa)

## Next Steps

<CardGroup cols={2}>
  <Card title="Check Transaction Status" icon="magnifying-glass" href="/api-reference/endpoints/transaction-by-ref">
    Monitor deposit status by transaction reference
  </Card>

  <Card title="Setup Webhooks" icon="webhook" href="/guides/webhooks">
    Receive real-time notifications for deposit events
  </Card>

  <Card title="Handle Refunds" icon="rotate-left" href="/api-reference/endpoints/refunds-create">
    Process refunds for completed deposits
  </Card>

  <Card title="Mobile Wallet Charging" icon="bolt" href="/api-reference/endpoints/payment-charge-mobile-wallet">
    Direct wallet charging with tokens
  </Card>
</CardGroup>