PostEx Dev Portal

Enable an existing card token for a different gateway by routing a PaymentIntent to that gateway and completing a successful 3D Secure payment.

This flow currently charges the customer. It isn't an authentication-only operation.

Before you begin#

The destination gateway must be configured for the merchant. You also need an existing XPay card token and a working saved-card 3DS integration.

Select the destination gateway#

XPay can select the destination through a configured routing rule or the gateway_instance_id supplied in the PaymentIntent request.

For rule-based selection, pass the applicable routing value as described in Payment routing. For direct selection, add:

JSON

{
  "gateway_instance_id": "{{gateway_instance_id}}"
}

Create the PaymentIntent#

Add the saved token and metadata.reason: "token" to the standard PaymentIntent request. The reason identifies that the successful transaction should create or update the token's gateway information.

JSON

{
  "token": "{{token_id}}",
  "metadata": {
    "reason": "token"
  },
  "gateway_instance_id": "{{gateway_instance_id}}"
}

This shortened direct-selection example omits the standard required PaymentIntent fields. When a routing rule selects the gateway, use the applicable metadata.rule_attribute instead of gateway_instance_id.

Complete the payment#

Render the Web, React Native, or Flutter saved-card element and complete the flow described in Authenticate a saved card with 3DS.

XPay adds or updates the destination gateway data on the token only after the transaction and authentication succeed. A failed or abandoned authentication leaves the existing token unchanged and doesn't add the destination gateway.

Verify gateway enablement#

After the payment succeeds:

Reconcile the PaymentIntent through the verified PAYMENT_INTENT_NOTIFICATION.
Retrieve the token details.
Confirm that the destination appears in the token's gateway array.

After verification, the same XPay token can be used for an eligible payment routed to that gateway.

Next steps#