B2B Payments Checkout Page

The Checkout Payment Link API allows you to create a hosted checkout page where customers can securely complete their payments.

Request Payload

To generate a checkout link, the following parameters must be passed:

amount: Transaction amount.
currency: Currency code (e.g., PKR).
customer: Customer information, including:
shipping: Shipping details including:
metadata: Order-related information such as order_reference.
success_url: The redirect URL where the customer will be sent after a successful payment.
failure_url: The redirect URL where the customer will be sent if the payment fails.
payment_methods: This is an optional field. If it is not provided, all enabled payment methods configured for the store will be displayed on the checkout. If you want to display only specific payment methods, you must pass them as an array of values in this field. Only the payment methods included in the array will be shown on the checkout.

bash

curl --location -g --request POST 'https://xstak-pay-stg.xstak.com/public/v1/payment/checkout' \
--header 'x-api-key: {{x-api-key-sk}}' \
--header 'x-account-id: {{x-account-id}}' \
--header 'x-signature: {{x-signature}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "amount": 5,
    "currency": "PKR",
    "customer": {
        "email": "testuser@gmail.com",
        "name": "user",
        "phone": "03415682456",

    },
    "shipping": {
        "address1": "Gulberg",
        "city": "Lahore",
        "country": "Pakistan",
        "zip": "65191",
        "shipping_method": "Standard",
        "province": "Punjab"
    },
    "metadata": {
        "order_reference": "checkout-pl-02"
    },
    "success_url": "https://webhook.site/abd82b58-bf61-4d68-b4b3-7688f01b4e92",
    "failure_url": "https://www.google.com/",
    "payment_methods": ["card", "jazzcash"]
}'

API Response

javascript

{
    "success": true,
    "responseStatus": "OK",
    "message": "Request processed successfully.",
    "data": {
        "_id": "xpay_pi_60be1502705b8505d99529b5cdef5333efda24fb544b43e75c2494ebffbb3533",
        "pi_client_secret": "xpay_pi_60be1502705b8505d99529b5cdef5333efda24fb544b43e75c2494ebffbb3533_cs_9e04a0a842e5eae8eb85a3696c768586bf6451f935c7bab8e6275969d8dca3e1",
        "created_at": "2025-09-16T13:00:11.045Z",
        "amount": 5,
        "currency": "PKR",
        "refund": {
            "refunded_amount": 0,
            "refund_object_id": null
        },
        "object_name": "payment_intent",
        "customer": {
            "name": "user",
            "email": "testuser@gmail.com",
            "phone": "03415682456",
            "vip_customer": "Yes",
            "previous_customer": "Yes"
        },
        "description": "",
        "pi_status": "requires_payment_method",
        "pm_token": "",
        "shipping": {
            "address1": "Gulberg",
            "address2": "",
            "city": "Lahore",
            "country": "Pakistan",
            "firstName": "",
            "lastName": "",
            "phone": "",
            "province": "Punjab",
            "zip": "65191",
            "shipping_method": "Standard"
        },
        "metadata": {
            "order_reference": "checkout-pl-03"
        },
        "token": null,
        "capture_method": "automatic",
        "html_response": {},
        "bank_response": {},
        "last_payment_response": {
            "token": null
        },
        "encryptionKey": null,
        "billingAddress": {},
        "routing_rules_history": [],
        "subscription": {},
        "checkout_page_url": "https://xpay-checkout-stage.xstak.com/?source=headless&order_id=checkout-pl-03&id=670cc16ca4f54be748916396"
    }
}

You should use the value from the "checkout_page_url" key, which provides the checkout page link for processing the payment.

Signature Generation

For each API request, a signature must be generated to ensure the integrity and authenticity of the payload.

Data Preparation

Key Source

Use the crypto library to generate an HMAC with SHA256, using your HMAC Secret Key (hmac_sc_api) as provided in the XAP Portal:

javascript

let hash = crypto
  .createHmac('SHA256', hmac_sc_api)
  .update(data)
  .digest('hex');

Key Source

Regeneration on Payload Change

Webhooks

After the payment journey is completed, the webhook will be received on your server.
For webhook guides, please follow the link.