Set up a JazzCash subscription#

Use the JazzCash subscription setup flow to collect a reusable JazzCash token for recurring payments.

Your backend creates a setup session with the customer’s JazzCash phone number and redirect URLs. Redirect the customer to the returned JazzCash page, where they enter their MPIN and OTP. After a successful setup, XPay sends a webhook containing the token you can store for future recurring charges.

Before you begin#

You need:

• An active XPay merchant account with JazzCash configured.
• Your XPay API credentials and request-signing secret.
• A customer’s JazzCash phone number.
• Public HTTPS URLs for successful and failed setup outcomes.
• A webhook endpoint configured on the XPay portal.

Create this request from your backend. Do not expose API credentials or request-signing secrets in browser or mobile app code.

How the flow works#

1. Your backend creates a JazzCash subscription setup session.
2. XPay returns a redirect_url.
3. Redirect the customer to that URL.
4. The customer enters their JazzCash MPIN and OTP.
5. JazzCash redirects the customer to your success or failure URL.
6. XPay sends a webhook to your configured endpoint.
7. After a successful setup, store the token from token._id in the verified webhook payload for future recurring payments.

A redirect helps you return the customer to your application. Use the verified webhook result to confirm whether token creation succeeded.

Create a subscription setup session#

Send a POST request to:

{{base_url}}/public/v1/subscription/wallet/setup

Generate x-signature on your backend from the exact serialized request payload.

Handle the response#

A successful request returns a redirect_url.

{
  "success": true,
  "responseStatus": "OK",
  "message": "Request processed successfully.",
  "data": {
    "redirect_url": "https://xpay-checkout-stage.xstak.com/wallet/payment-setup?id=670cc16ca4f54be748916396&payment_setup_id=xpay_wallet_ad5fa24d4a4849768362789699b95d3b"
  }
}

Redirect the customer to data.redirect_url to complete the JazzCash authentication flow.

Confirm token creation#

When the customer completes the flow successfully, XPay sends a webhook to the endpoint configured for the store.

Verify the webhook signature before processing it. After verification:

1. Confirm that the setup completed successfully.
2. Read the reusable token from token._id.
3. Store the token against the correct customer in your system.
4. Use the stored token only for future recurring payments for that customer.