Handle 3D Secure | CentaPay

3D Secure#

Most Kazakhstan and Uzbekistan card transactions trigger 3DS authentication. Your integration must handle the redirect flow before going to production.

3DS Flow#

Send SALE request

Your server posts to CentaPay as normal.

Receive REDIRECT response

Response contains result: REDIRECT, status: 3DS, and redirect_url.

Redirect cardholder to ACS

Build an HTML form or JS redirect to send the customer to the issuer's 3DS page.

Cardholder authenticates

SMS code, biometric, or frictionless flow on the issuer's page.

Return to your site

Customer returns to your term_url_3ds.

Receive callback

CentaPay sends the final result (SUCCESS or DECLINED) to your callback URL.

Handling the Redirect#

The SALE response for a 3DS transaction contains:

Field	Description
`redirect_url`	URL to redirect the cardholder to
`redirect_params`	Object of 3DS parameters (key-value pairs). May be an empty array or absent entirely.
`redirect_method`	`POST` or `GET`

⚠️

redirect_params varies by acquirer. It may contain PaReq, TermUrl, or other values. It may also be empty or missing (commonly when redirect_method=GET). Always check for its presence before processing.

Option 1: HTML Form (POST or GET)

// Build auto-submitting form from SALE response
$html = '<form id="3ds" method="'
  . $response['redirect_method']
  . '" action="' . $response['redirect_url'] . '">';

if (!empty($response['redirect_params'])
    && is_array($response['redirect_params'])) {
    foreach ($response['redirect_params'] as $k => $v) {
        $html .= '<input type="hidden" name="'
          . htmlspecialchars($k) . '" value="'
          . htmlspecialchars($v) . '">';
    }
}
$html .= '</form>';
$html .= '<script>document.getElementById("3ds").submit();</script>';
echo $html;

Option 2: JavaScript Redirect (GET with query params)

If redirect_method=GET and the URL already contains query parameters:

document.location = response.redirect_url;

Alternative Endpoint: /v2/post#

The standard endpoint /post returns redirect_params as a key-value object. The alternative endpoint /v2/post returns them as an array of {name, value} objects:

"redirect_params": {
  "PaReq": "eJxVUt1...",
  "TermUrl": "https://..."
}

"redirect_params": [
  {"name": "PaReq", "value": "eJxVUt1..."},
  {"name": "TermUrl", "value": "https://..."}
]

term_url_target#

If your checkout runs inside an iframe, use term_url_target to control where the customer returns after 3DS. Values: _blank, _self, _parent, _top (default), or a custom iframe name.