Payment routing

Route an eligible payment through XPay configuration by supplying a merchant-defined routing attribute, or select a specific configured gateway instance when the integration requires direct selection.

Before you begin#

Configure the applicable gateway instances and routing rules in the XPay Merchant Portal. Keep the routing values used by the merchant application aligned with that configuration.

Use a routing-rule attribute#

Add the merchant-defined value to PaymentIntent metadata as a string:

{
  "metadata": {
    "order_reference": "order-1003",
    "rule_attribute": "bill_payment"
  }
}

XPay evaluates metadata.rule_attribute against the routing rules configured for the merchant.

Select a gateway instance#

When the merchant must select a specific configured gateway instance, include its identifier in the PaymentIntent request:

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

Use the ID supplied by XPay configuration rather than a gateway display name. Do not combine direct gateway selection with rule-based routing unless the applicable XPay contract defines which instruction takes precedence.

Retrieve configured routing rules#

Retrieve the routing rules configured for the store from the merchant backend:

GET {{base_url}}/public/v1/payment/routing/rules/gateway

The response identifies whether each rule is enabled, its primary gateway type, its fallback gateway types, and the merchant-defined rule attributes:

[
  {
    "rule_id": "rule_01",
    "enabled": true,
    "gatewayType": "{{primary_gateway_type}}",
    "fallback_gateway": [
      {
        "gateway_type": "{{fallback_gateway_type}}"
      }
    ],
    "rule_attributes": [
      "bill_payment"
    ]
  }
]

Use the configured attribute values in metadata.rule_attribute. Do not derive routing instructions from a gateway's display name.

Reconcile the payment#

Store the PaymentIntent ID and merchant order reference regardless of the selected route. Use the accepted PaymentIntent response and verified webhook outcome to determine the payment result.

Next steps#

• Create a PaymentIntent.
• PaymentIntent lifecycle and statuses.
• Use the Create Payment Intent API for complete routing-related fields and the response schema.