Redirects and returns

After a payment completes, the customer is redirected back to your site. This page covers the redirect URLs you supply, how to handle the customer's arrival, the redirect methods available, and how to verify the return parameters.

Customer return after payment

The platform can redirect the customer to one of the following URLs after payment completion (success, decline, or close). You supply these URLs in the authentication request:

URL	When the customer is sent here
success_url	After a successful payment.
cancel_url	After the configured number of decline attempts is reached, or when the customer closes the form (after pressing Pay).
expiry_url	When the session expires before completion.
error_url	On a Checkout-side technical error (rare).

All four URLs must be publicly reachable HTTPS endpoints on your domain. If a URL is missing from the authentication request, the customer sees a default Payment Platform page instead of being redirected.

Redirect types

When a payment requires a redirect (for example, to a 3DS page or an alternative payment method provider), Payment Platform supports two approaches for delivering the redirect data to the customer's browser.

Standard redirect

Payment Platform returns redirect_url, redirect_params, and redirect_method (POST or GET) in the API response. Your server builds an HTML form or JavaScript redirect and serves it to the customer's browser.

Use this option by default. It works for all integrations.

Enabling return parameters

By default, the customer is redirected to success_url or cancel_url with no query parameters.

These return parameters are appended to success_url and cancel_url for both 3DS and non-3DS payments. The redirect back to your site carries the same parameters whether or not the payment went through a 3DS challenge. Configure which parameters are returned in Protocol Mapping; validate them with the customer-return signature, and treat the callback as the source of truth for the final status.

If you enable Return parameters in Configuration > Protocol Mappings, the redirect URLs receive the following query parameters:

Parameter	Description
payment_id	Public payment ID (UUID).
trans_id	Transaction ID (UUID).
order_id	Your order number, echoed back.
hash	Signature for verifying the redirect is genuine.
brand	Payment method brand. Configure this in the Protocol Mappings modules by enabling the Return parameters attribute and double-click or drag-and-drop to move the item under Return additional parameters.
payment_method	Payment method used. Configure this in the Protocol Mappings modules by enabling the Return parameters attribute and double-click or drag-and-drop to move the item under Return additional parameters.

warning

Return parameters are sent only to success_url and cancel_url. The expiry_url and error_url redirects do not carry query parameters.

info

The cancel_url redirect carries query parameters only after a real decline followed by the customer pressing the close button. If the customer closes the page without ever pressing Pay, no redirect happens.

Handling the customer arrival

When the customer lands on your success_url or cancel_url, we recomenf these guidelines:

info

The following content is only a recommendation, the final decision on how to handle customers is in your side.

On success_url

1. Show a "payment received" confirmation page, but do not fulfill the order yet.
2. Wait for the callback. The redirect and the asynchronous callback can arrive in either order. The callback to your notification_url is the source of truth, not the redirect. A customer arriving at success_url means the payment likely succeeded, but only the callback confirms the final status.
3. Verify the hash if return parameters are enabled. Compute the expected hash using the customer-return signature formula and compare it to the hash query parameter. If they do not match, treat the redirect as potentially tampered with.
4. Poll as a fallback. If the callback has not arrived within a reasonable window (e.g. 30 seconds), use the Get transaction status endpoint to check the payment state. Do not rely on polling as the primary mechanism.

On cancel_url

1. Show a "payment not completed" page with an option to retry.
2. Check the query parameters (if enabled). The payment_id and order_id let you correlate the cancellation to the original order in your system.
3. Do not assume the payment failed permanently. In some edge cases (network issues, browser back-button), a customer may land on cancel_url even though the payment was actually processed. Always check the callback or poll the status before marking the order as failed.

Race condition between redirect and callback

The redirect (customer arriving at your URL) and the callback (server-to-server POST to your notification_url) are independent events. Either can arrive first. Design your order-status logic to handle both sequences:

• Callback arrives first: update the order status immediately. When the customer arrives at success_url, your page already knows the result.
• Redirect arrives first: show a pending state ("Confirming your payment...") and update the page when the callback arrives or after polling confirms the status.

tip

Store the payment status in your database keyed by payment_id or order_id. Both the callback handler and the return-URL page read from the same record. This avoids race conditions regardless of which event arrives first.

Customer-return signature verification

When return parameters are enabled, verify the hash to confirm the redirect was not tampered with. The signature formula is documented in Hash signature.

If the computed hash does not match the hash parameter in the URL, do not trust the redirect data. Log the mismatch for investigation and fall back to polling the transaction status via API.