Redirect / 3DS handling

3DS (3-D Secure) is the cardholder-not-present verification step issuers run during card payments. On S2S CARD, Payment Platform handles the protocol-level exchange with the issuer's Access Control Server (ACS); the merchant runs the cardholder redirect and consumes the result. This page covers when a redirect is required, how to implement it, and how to interpret the authentication outcome.

When 3DS fires

3DS can be triggered by any of the following:

1. Issuer mandate. The card's issuer requires step-up authentication based on its own rules.
2. Region or regulation. PSD2 in the EU and similar regulations elsewhere require strong customer authentication for most card payments.
3. MID configuration. The merchant's MID is set to require 3DS regardless of issuer mandate.

Whenever the response to your payment request returns result = REDIRECT, handle it the same way: redirect the payer to the provided URL. The redirect is not always a 3DS challenge — it can also be used to collect additional metadata or to request extra information from the payer (for example, a birth date that was not passed in the request is collected during the interaction instead of declining the payment). The handling on the merchant side is identical in every case.

The redirect / 3DS flow on S2S CARD

1. The merchant sends a SALE or AUTH request with card data.
2. Payment Platform initiates the 3DS exchange with the issuer's ACS.
3. If payer interaction is required, Payment Platform returns a redirect_url in the response. The merchant redirects the cardholder to that URL. The cardholder completes the interaction. The ACS redirects to term_url_3ds. Payment Platform validates the result, then the payment proceeds (or fails).
4. Payment Platform sends a callback to the merchant's callback URL with the final order_status and the 3DS attributes. See What the callback carries.

Where the callback URL comes from

The callback URL is not a field of the SALE / AUTH request. notification_url is a value configured by an admin for your merchant profile in the admin panel. Alternatively, you can submit the callback in the request.

The term_url_3ds field

term_url_3ds goes on the original SALE or AUTH request. It is the URL the ACS will redirect back to after the cardholder completes the interaction; Payment Platform proxies this redirect and finalises the payment. It should be a publicly reachable URL: if it is unreachable the cardholder can get stuck on the ACS confirmation screen and the payment hangs. Check with your account manager for the exact connectivity, HTTPS, and response-time requirements your account is configured to enforce.

Handling the Redirect / 3DS response

If your account supports 3D-Secure and the card supports 3D-Secure, Payment Platform returns the link to the issuer's ACS for verification. You then redirect the cardholder to that link. If the response contains parameters in addition to the link, you must forward those parameters along with the redirect using the method indicated in the response.

After verification on the ACS side, the cardholder returns to your site using the URL you specified in the SALE request, and Payment Platform delivers the final transaction status to your notification_url.

Redirect via the system wrapper

Instead of handling the response fields with additional logic on your side, the redirect can be performed using the system wrapper: the response returns a short link, and you only need to redirect the payer to it — the link handles all the acquirer parameters instead of the merchant. To enable this option, contact your administrator or account manager; it is enabled in the Protocol Mapping settings.

Response fields

For any redirect-triggered transaction, the response includes:

• redirect_url: the URL the merchant should redirect the customer to.
• redirect_params: an object containing 3DS parameters specific to this transaction. It is an empty array when there are no parameters.
• redirect_method: the method of transferring the parameters (POST or GET).

The availability of redirect_params depends on the data the acquirer sends. redirect_params may be missing entirely; this typically happens when redirect_method is GET.

redirect_params values vary by acquirer. Common keys include PaReq, TermUrl, and many others. Each acquirer can send values in different ways; the interface is unified so the same merchant code can handle redirects to every 3DS version regardless of acquirer.

Redirect flow

In general, the redirect works as follows:

1. Receive the response from Payment Platform.
2. Check whether it contains redirect data and the associated parameters.
3. If redirect data is present, generate an HTML document with a form (or use a client-side redirect).
4. Return that HTML to the cardholder's browser.

The cardholder's browser then handles the redirect automatically.

Form encoding for GET with query parameters

If redirect_method is GET and redirect_url already contains query parameters (for example https://example.domain.com/?parameter=1), you must merge those parameters into the form inputs rather than appending them again to the URL. Otherwise duplicate parameters can confuse the ACS.

Two implementation approaches

Option 1: HTML form with query parameters as inputs

Parse the query parameters from redirect_url and pass them as form input elements in an HTML form.

<form action="https://example.domain.com" method="GET">
  <input name="parameter" value="1">
  <input type="submit" value="Go">
</form>

Option 2: JavaScript redirect

Use JavaScript to redirect the cardholder to redirect_url with the query parameters intact.

document.location = "https://example.domain.com/?parameter=1";

Choose Option 1 when you need a deterministic POST or when the cardholder's browser may block automatic JS redirects. Option 2 is simpler for GET flows.

iframe break-out

If the merchant embeds the checkout flow in an iframe, the 3DS challenge may need to break out of the iframe (most ACS servers refuse to render inside one). The MID's Override Link Target setting controls this behaviour: when set, the cardholder sees an intermediate wrapper with a button that opens the ACS challenge in a new top-level window. Confirm the exact wrapper UI with your account manager, since it varies by configuration.

What the callback carries

When the transaction reaches its result, Payment Platform sends a callback to your notification_url. Your server must respond with the string OK if the data was received successfully, or ERROR otherwise. Use the callback as the source of truth for the final transaction status.

The main parameters below are always returned in the callback:

Parameter	Description
action	The action the callback refers to (SALE, CAPTURE, CREDITVOID, VOID, DEBIT, CREDIT2CARD, CARD2CARD, RETRY, CHARGEBACK)
result	Result of the operation (SUCCESS, DECLINED, REDIRECT, UNDEFINED)
status	Actual status of the transaction in Payment Platform
order_id	Transaction ID in the Merchant's system
trans_id	Transaction ID in Payment Platform
hash	Special signature used to validate the callback (see Appendix A)

Depending on the action and result, the callback also carries the payment details (trans_date, amount, currency, descriptor, decline_reason, and others). The full per-action callback tables are in Payment operation types.

Additional optional parameters can be configured and returned via Add Extended Data to Callback in the admin panel (Configurations → Protocol Mappings): connector_name, rrn, approval_code, gateway_id, extra_gateway_id, merchant_name, mid_name, merchant_key, issuer_country, issuer_bank, arn, extended_data, brand.

3DS authentication attributes

The 3DS attributes below can be configured (Protocol Mapping → Add Data to Callback) and are returned only if Payment Platform receives them from the acquirer or if an external MPI is used. Confirm the available fields with your account manager.

Field	Description
threeDSServerTransID	3DS Server transaction ID. Identifies the authentication session end-to-end.
dsTransID	Directory server transaction ID (Visa, Mastercard, or other scheme).
acsTransID	ACS (issuing bank) transaction ID.
xid	Main 3DS v1.0 transaction ID. Empty for 3DS v2 flows.
transStatus	The authentication result. See the table below.
transStatusReason	Reason code accompanying transStatus. Useful when the status is non-success.
eci	Electronic Commerce Indicator. Maps to liability shift conditions per scheme.
protocolVersion	1.0.2, 2.1.0, 2.2.0, etc.
authenticationFlow	01 for frictionless, 02 for challenge.

transStatus values

Value	Meaning	Recommended action
Y	Authenticated successfully. Liability shift to the issuer typically applies; confirm with your scheme rules and the eci value on the callback.	Proceed with the payment.
N	Not authenticated. Cardholder failed verification.	Treat as declined; do not charge.
U	Unable to authenticate. ACS could not complete (technical issue).	Decide per risk policy: decline, or fall back to non-3DS with full merchant liability.
A	Attempted. Issuer not enrolled; merchant attempted authentication.	Liability shift varies by scheme; usually safe to proceed.
C	Challenge required. The cardholder must complete the ACS challenge.	A follow-up callback arrives once the challenge finishes.
R	Rejected by issuer.	Treat as declined.
I	Informational only (3RI / 3DS-Requestor Initiated).	Not used in standard payment flows.

ECI values

eci works alongside transStatus to determine liability:

• 05 (Visa) / 02 (Mastercard): fully authenticated, liability shifts.
• 06 (Visa) / 01 (Mastercard): attempted authentication, liability shifts in most cases.
• 07 (Visa) / 00 (Mastercard): no authentication, full merchant liability.

Browser metadata attributes

Also configurable under Protocol Mapping → Add Data to Callback. These fields carry the payer's browser data gathered by the collector during the redirect / 3DS flow: if the payment went through an external MPI the data is stored as-is; through the connector-service it is populated by the collector. For S2S, if the collector was not invoked (for example, a frictionless authentication with no redirect), the fields remain empty.

Field	Example	Description
browser_color_depth	24	Screen color depth in bits.
browser_screen_height	1080	Screen height in pixels.
browser_screen_width	1920	Screen width in pixels.
browser_java_enabled	FALSE	Java support flag.
browser_javascript_enabled	TRUE	JavaScript availability flag.
browser_language	uk-UA	Language set in the browser.
browser_timezone_offset	-180	Minutes between UTC and local time.
browser_user_agent	Mozilla/5.0 ...	User-Agent string.
browser_accept_headers	text/html, ...	HTTP Accept header.
browser_platform	Win32	Payer's operating system.

Card-On-File attributes

The initiator, sequence, and source Card-On-File attributes can also be enabled for the callback under Protocol Mapping. They are not sent by default. See the Card-On-File fields in the get-status response for their values and meaning.

Common failures

Symptom	Likely cause	Fix
transStatus=C then nothing	Cardholder abandoned the challenge	Treat as soft failure; allow retry.
transStatus=Y but payment still declines	Authentication passed; the acquirer declined for another reason	Inspect the connector response in the callback for the decline code.
Cardholder stuck on the ACS redirect	term_url_3ds is not publicly reachable	Verify the URL is publicly reachable and responds quickly.
eci=07 or 00 even with transStatus=Y	Issuer authenticated but scheme rules don't grant liability shift	Decide per risk policy whether to proceed.

What's next

• Payment operation types for what to do once the redirect completes (capture, void, recurring).
• S2S Card overview for the broader integration context.
• Errors and testing for sandbox-based debugging.