3DS and hosted checkout

What to expect from 3DS

1. Successful authentication doesn't mean the charge succeeded. Authentication only proves that the payer is the cardholder. The issuer can still decline the charge, so rely on the payment's status.
2. The platform can't guarantee that payers never see an authentication challenge. Authentication may need no interaction, or the payer may have to complete a challenge on the bank's page. The issuer and the provider decide.
3. You can't bypass the provider's or the issuer's authentication requirements through merchant configuration.

When authentication is required

In the test environment, use the 3DS test cards to simulate outcomes such as no interaction needed, a successful challenge, a failed challenge and a successful authentication followed by a declined charge.

Handle next_action.redirect_to_url

See next_action in the API reference.

• Full-page redirect: Return next_action.url from your server to the payer's browser and redirect the whole page. Don't put it in an iframe (the authentication page can't be embedded in third-party pages). In an app, open it in the system browser or an in-app browser tab.
• The issuer challenge always completes inside the platform's authentication page, which shows the issuer's page in an embedded frame or through a full-page redirect, depending on the provider's requirements. You don't need to integrate the provider's 3DS SDK on your page, and you can't.
• Validity period: At most 10 minutes, as set by next_action.expires_at (the shorter of the platform's cap and the provider session's validity period).
• Security: The authentication URL carries a short-lived credential that is bound to this one authentication only, so it can't be used for other orders. Don't write it to logs, analytics tools or error reporting. Don't put it in the URL of your own page (query parameter or hash), or it can leak through the Referer header or analytics scripts.
• Don't collect issuer passwords or SMS verification codes on your page. The payer enters challenge information only in the authentication flow that the issuer or the provider supplies.
• Authentication that needs interaction can't be completed by your server on behalf of the cardholder: the payer must be present when you start the payment.
• For now, type has only one value, redirect_to_url. If you get a type you don't recognize, treat the payment as "not completed" and query it. Don't treat it as success.

After authentication

After the payer completes authentication, the browser returns to the return_url you provided when you created or confirmed the payment.

You can reproduce each outcome above in the test environment with the 3DS test cards.

Collect browser information

browser_info is used for 3DS risk assessment and must come from the payer's real browser. Whether a field is required depends on the provider's current capabilities. If a required field is missing, the API returns 400 before it submits anything to the provider and names the field in error.field. We recommend always providing every field.

See browser_info in the API reference.

// Collect this in the payer's browser and submit it to your server together with the card details
export function collectBrowserInfo() {
  return {
    user_agent: navigator.userAgent,
    language: navigator.language,
    screen_width: window.screen.width,
    screen_height: window.screen.height,
    color_depth: window.screen.colorDepth,
    timezone_offset_minutes: new Date().getTimezoneOffset(), // UTC+8 is -480
    javascript_enabled: true
  };
}

timezone_offset_minutes follows the sign convention of JavaScript's getTimezoneOffset(), which is the opposite of how "UTC+8" is written:

The value for the same region changes during daylight saving time, so collect it live when the payer pays and never hard-code it. 203.0.113.x in the examples is a reserved documentation address. Don't use it in the live environment.

How hosted checkout works

• Checkout runs on a separate platform domain. Card details are received inside checkout by an isolated collection component: either a provider-hosted component or an isolated iframe on a separate platform subdomain. The platform chooses based on the provider's capabilities, and it makes no difference to your integration. Neither your page nor your server touches card data, and the create request contains none either.
• Checkout shows the merchant display name, the order summary (description), the amount and the currency. It never shows your server-side key.

Two ways to create a checkout session

Both methods require an Idempotency-Key. For an example of method B, see the Quickstart. Method A:

# Method A: create a checkout session for an existing payment (for example, one created with confirm=false)
curl https://api.payhub.example/v1/checkout/sessions \
  -H "Authorization: Bearer <TEST_SERVER_API_KEY>" \
  -H "Idempotency-Key: order-demo-008-session-v1" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_id": "<PAYMENT_ID>",
    "return_url": "https://merchant.example/payment/return",
    "cancel_url": "https://merchant.example/payment/cancel",
    "locale": "en"
  }'

The API returns these errors: 400 invalid_request if you pass both groups of parameters or neither, 403 capability_disabled if the currency isn't enabled in the current environment (this check runs before the amount check), 422 order_amount_mismatch if the amount or currency doesn't match the existing order, 422 url_not_allowed if the redirect URL isn't registered, and 409 if the order can't be paid. For all fields and response examples, see POST/v1/checkout/sessions.

Session reuse and validity period

Checkout language

locale uses BCP 47. A value that starts with zh shows Chinese and a value that starts with en shows English. For any other value, or if you don't pass one, checkout uses the merchant's default language. Payers can also switch the language in the checkout footer.

Redirect URL allowlist

• return_url and cancel_url (and return_url in the direct API) must match a rule you registered in advance (Register redirect URLs (opens the merchant portal in a new tab) (Test environment; Requires Owner, Admin or Developer)). Otherwise the API returns 422 url_not_allowed.
• Rules are registered per environment. Each rule consists of a scheme + a host (an exact host, or a one-level wildcard such as *.example.com) + an optional port + an optional path prefix.
• Path prefixes match by path segment: /pay matches /pay/return but not /payment. The query string and the fragment aren't part of the match.
• The live environment allows only https. In the test environment, you can also register local addresses such as http://localhost.
• When the platform redirects the payer back, it uses the URL you provided exactly as is and appends no parameters.

Returning to the merchant doesn't cancel the charge

When the payer clicks "Return to merchant" (cancel_url), that doesn't cancel a charge that was already submitted. Your cancel_url page must retrieve the payment first. If the payment is still in flight, show "Confirming". If you've confirmed that no charge is in flight and you need to close the order, call POST/v1/payments/{payment_id}/cancel and rely on status=canceled.

Fulfill based on server-side status

• The browser returning to return_url is for the payer experience only.
• The only valid basis for fulfillment is status=succeeded from a server-side query, or a payment.succeeded event whose signature you've verified (for the verification method, see Verify webhook signatures).
• URL parameters (including an order ID you added yourself) are never a result. Treat them only as a hint about which payment to look up.
• Authentication and checkout credentials are bound to a single object: the credential for order A can't act on order B. Don't reuse these URLs across orders in your own system either.

// return_url / cancel_url page: display only. The server-side query decides the outcome; URL parameters are only a hint for finding the order
app.get('/payment/return', async (req, res) => {
  const order = await findOrderForSession(req.session.userId); // Find the order from your session or order table
  const payment = await getPayment(order.paymentId); // Retrieve the latest status on the server
  switch (payment.status) {
    case 'succeeded':
      return res.render('paid', { order }); // A webhook or a server-side query triggers fulfillment; the page only displays the result
    case 'failed':
      return res.render('failed', { order, message: payment.failure?.message }); // The payer can reopen checkout and use another card
    case 'canceled':
    case 'expired':
      return res.render('closed', { order });
    default:
      return res.render('confirming', { order }); // processing / requires_action / unknown: show "Confirming"
  }
});

FAQ