Collect a payment token with XPay Element

Use XPay Element to collect a customer's card details and create a reusable payment token. XPay delivers the reusable token ID to the merchant webhook endpoint.

Before you begin#

You need a merchant backend, a customer-facing application with a supported XPay SDK, and a public HTTPS endpoint configured according to Integrate XPay webhooks.

Sensitive card values must remain inside XPay Element. Do not collect or submit them through merchant-controlled fields.

Token flow#

1. The frontend asks the merchant backend to start token collection.
2. The backend creates a PaymentIntent with metadata.reason set to token.
3. The backend returns the PaymentIntent client secret and encryption key to the frontend.
4. The frontend renders XPay Element and calls confirmPayment().
5. XPay completes any customer authentication required for the payment method.
6. XPay sends the payment result and token to the configured webhook endpoint.
7. The merchant verifies the webhook and reads the token ID from token.id.
8. The merchant associates the token with the correct customer record.

Create the token PaymentIntent#

Send the standard PaymentIntent request with the token reason:

{
  "amount": 10,
  "currency": "PKR",
  "payment_method_types": "card",
  "customer": {
    "_id": "{{customer_id}}",
    "name": "Ayesha Khan",
    "email": "ayesha@example.com",
    "phone": "{{customer_phone}}"
  },
  "metadata": {
    "order_reference": "token-request-1001",
    "reason": "token"
  },
  "gateway_instance_id": "{{gateway_instance_id}}"
}

Include customer._id when the XPay customer already exists and the new token must be associated with that customer.

Confirm in the frontend#

For Web SDK v5, use the object form of confirmPayment():

await xpay.confirmPayment({
  paymentMethodType: "card",
  clientSecret: paymentIntent.pi_client_secret,
  customer: { name: "Ayesha Khan" },
  encryptionKey: paymentIntent.encryptionKey
});

Use the SDK outcome to update the customer interface. Do not mark token storage as complete until the merchant backend accepts the verified webhook.

Store the token#

After signature verification:

1. Match the webhook PaymentIntent ID to token-request-1001.
2. Confirm the successful tokenization result.
3. Read the token ID from token.id.
4. Store the token ID and only the display information required by the merchant interface.
5. Associate the token with the correct XPay and merchant customer records.

Do not send reusable payment tokens to untrusted frontend code or include them in application logs.

Next steps#

• Manage saved tokens.
• Pay with a saved token.
• Use the token as payment.token when a supported subscription flow requires it.
• See the Create Payment Intent API for the complete request and response schema.