Handle transport failures, XPay API errors, payment outcomes, and uncertain network results as separate conditions. An HTTP success does not necessarily mean that a payment has reached its final successful state.
Read the response envelope
XPay responses can include an envelope like this:
{
"success": true,
"responseStatus": "OK",
"message": "Request processed successfully.",
"data": {
"_id": "xpay_pi_example",
"pi_status": "requires_payment_method"
}
}The example is shortened. Use the XPay API reference for the response schema of a specific endpoint.
Separate failure categories
Log safe diagnostic context
Where XPay returns a request or correlation identifier, store it with:
- The endpoint and HTTP method.
- The HTTP status code.
- The XPay resource ID.
- The merchant order reference.
- The non-sensitive error code and message.
Do not log API credentials, HMAC secrets, signatures, sensitive card values, encryptionKey, pi_client_secret, or reusable payment tokens.
Handle an uncertain result
If the connection closes or times out after the request is sent, do not assume the operation failed. Use the merchant reference and stored XPay identifier to retrieve or reconcile the current resource through a documented endpoint or verified webhook.
Do not blindly repeat create, payment, capture, or refund operations unless the endpoint explicitly documents an idempotency mechanism.