PayU-Handled 3DS Authentication

PayU-handled 3DS authentication prevents the need for you to manage the 3DS integration process. PayU takes care of everything, from communicating with the issuing bank to handling the authentication flow.

To enable 3DS authentication, contact your PayU representative or technical support. Once enabled, include the req3DSAuthentication parameter in your payment requests using PayU’s Payments API.

Considerations

3DS authentication with PayU Latam is only available in Argentina, Brazil, Colombia, Mexico, and Peru.
When using 3DS authentication in API integrations, setting a RESPONSE_URL is mandatory. If not provided, the transaction will return an error.
If you use a WebCheckout integration, contact your PayU representative or technical support to confirm whether 3DS authentication is available for your transactions.
Supported networks: Visa and Mastercard.

The `req3DSAuthentication` Parameter

This parameter enables you to specify whether a transaction requires 3DS authentication. The parameter supports the following values:

"true": Enforces 3DS authentication for the transaction.
"false": Disables 3DS authentication for the transaction.

If your request doesn’t include req3DSAuthentication, PayU’s risk engine will determine whether the transaction requires 3DS authentication based on its risk assessment.

Parameters for 3DS Authentication

The table below outlines the key parameters associated with 3DS authentication. For a complete list of parameters applicable to credit or debit card transactions, refer to the Payments API documentation for your country.

Field Name	Format	Size	Description
`transaction > req3DSAuthentication`	Boolean	4-5 characters	Specifies whether 3DS authentication is enforced (`true` or `false`). If omitted, PayU’s risk engine decides whether authentication is required.
`transaction > order > notifyUrl`	Alphanumeric	Up to 255 characters	Webhook URL that your integration uses to receive the final transaction status (e.g., approved or rejected) from PayU. For a detailed list of possible statuses, refer to the response codes documentation.
`transaction > extraParameters > RESPONSE_URL`	Alphanumeric	Up to 255 characters	URL where the user is redirected after completing the 3DS authentication, typically a page on the merchant’s website. For API integrations, this parameter is mandatory. If not provided, the transaction may fail because PayU cannot redirect the user after the authentication challenge. For a detailed list of possible statuses, refer to the response codes documentation.

Request Example

In the following request example, req3DSAuthentication is set to true to require 3DS authentication:

{
    "language": "en",
    "command": "SUBMIT_TRANSACTION",
    "merchant": {
        "apiLogin": "pRRXKOl8ikMmt9u",
        "apiKey": "4Vj8eK4rloUd272L48hsrarnUA"
    },
    "transaction": {
        "order": {
            "language": "en",
            "signature": "8b9abb9dcae76d331e4493a559e8a76a0a9296e6944d460303d5639d9230c485",
            "accountId": "512321",
            "description": "PayULatamAPI|Test|CO|COL",
            "referenceCode": "REFERENCIA_PRUEBA_12345",
            "notifyUrl": "https://merchant-mywebhook.com",
            "buyer": {
                "merchantBuyerId": "Merchant_Buyer_ID_123",
                "fullName": "John Doe",
                "emailAddress": "john.doe@email.com",
                "contactPhone": "3155555555",
                "dniType": "CC",
                "dniNumber": "123456789",
                "shippingAddress": {
                    "country": "CO",
                    "state": "DC",
                    "city": "Bogotá",
                    "postalCode": "110111",
                    "street1": "Calle 100",
                    "street2": "Cra 9",
                    "phone": "6011234567"
                }
            },
            "shippingAddress": {
                "country": "CO",
                "state": "DC",
                "city": "Bogotá",
                "postalCode": "110111",
                "street1": "Calle 100",
                "street2": "Cra 9",
                "phone": "6011234567"
            },
            "additionalValues": {
                "TX_VALUE": {
                    "value": "100",
                    "currency": "COP"
                },
                "TX_TAX": {
                    "value": "0",
                    "currency": "COP"
                },
                "TX_TAX_RETURN_BASE": {
                    "value": "0",
                    "currency": "COP"
                }
            }
        },
        "payer": {
            "merchantPayerId": "Merchant_Payer_ID_123",
            "fullName": "John Doe",
            "emailAddress": "john.doe@email.com",
            "contactPhone": "3155555555",
            "dniType": "CC",
            "dniNumber": "123456789",
            "billingAddress": {
                "country": "CO",
                "state": "DC",
                "city": "Bogotá",
                "postalCode": "110111",
                "street1": "Calle 100",
                "street2": "Cra 9",
                "phone": "6011234567"
            }
        },
        "creditCard": {
            "name": "APPROVED",
            "number": "5570898637920584",
            "expirationDate": "2025/12",
            "securityCode": "777",
            "processWithoutCvv2": false
        },
        "extraParameters": {
            "INSTALLMENTS_NUMBER": 1,
            "RESPONSE_URL": "https://merchant.shoppingresult.com"
        },
        "type": "AUTHORIZATION_AND_CAPTURE",
        "paymentMethod": "MASTERCARD",
        "paymentCountry": "CO",
        "ipAddress": "45.6.10.241",
        "userAgent": "Mozilla/5.0 (Windows; U; Windows NT 6.0) AppleWebKit/531.2.0 (KHTML, like Gecko) Chrome/21.0.885.0 Safari/531.2.0",
        "cookie": "sefejihsxeai037qhkwa3jex9",
        "deviceSessionId": "cb066830a3dcbdaf7234fd230d1959b0c6b3ae3ad5265490d55802a61738b537",
        "integrationMethod": "POST_API_v4_0",
        "req3DSAuthentication": "true",
        "source": "WEB"  
    },
    "test": false
}

<request>
    <language>en</language>
    <command>SUBMIT_TRANSACTION</command>
    <merchant>
        <apiLogin>pRRXKOl8ikMmt9u</apiLogin>
        <apiKey>4Vj8eK4rloUd272L48hsrarnUA</apiKey>
    </merchant>
    <transaction>
        <order>
            <language>en</language>
            <signature>8b9abb9dcae76d331e4493a559e8a76a0a9296e6944d460303d5639d9230c485</signature>
            <accountId>512321</accountId>
            <description>PayULatamAPI|Test|CO|COL</description>
            <referenceCode>REFERENCIA_PRUEBA_12345</referenceCode>
            <notifyUrl>https://merchant-mywebhook.com</notifyUrl>
            <buyer>
                <merchantBuyerId>Merchant_Buyer_ID_123</merchantBuyerId>
                <fullName>John Doe</fullName>
                <emailAddress>john.doe@email.com</emailAddress>
                <contactPhone>3155555555</contactPhone>
                <dniType>CC</dniType>
                <dniNumber>123456789</dniNumber>
                <shippingAddress>
                    <country>CO</country>
                    <state>DC</state>
                    <city>Bogotá</city>
                    <postalCode>110111</postalCode>
                    <street1>Calle 100</street1>
                    <street2>Cra 9</street2>
                    <phone>6011234567</phone>
                </shippingAddress>
            </buyer>
            <shippingAddress>
                <country>CO</country>
                <state>DC</state>
                <city>Bogotá</city>
                <postalCode>110111</postalCode>
                <street1>Calle 100</street1>
                <street2>Cra 9</street2>
                <phone>6011234567</phone>
            </shippingAddress>
            <additionalValues>
                <TX_VALUE>
                    <value>100</value>
                    <currency>COP</currency>
                </TX_VALUE>
                <TX_TAX>
                    <value>0</value>
                    <currency>COP</currency>
                </TX_TAX>
                <TX_TAX_RETURN_BASE>
                    <value>0</value>
                    <currency>COP</currency>
                </TX_TAX_RETURN_BASE>
            </additionalValues>
        </order>
        <payer>
            <merchantPayerId>Merchant_Payer_ID_123</merchantPayerId>
            <fullName>John Doe</fullName>
            <emailAddress>john.doe@email.com</emailAddress>
            <contactPhone>3155555555</contactPhone>
            <dniType>CC</dniType>
            <dniNumber>123456789</dniNumber>
            <billingAddress>
                <country>CO</country>
                <state>DC</state>
                <city>Bogotá</city>
                <postalCode>110111</postalCode>
                <street1>Calle 100</street1>
                <street2>Cra 9</street2>
                <phone>6011234567</phone>
            </billingAddress>
        </payer>
        <creditCard>
            <name>APPROVED</name>
            <number>5570898637920584</number>
            <expirationDate>2025/12</expirationDate>
            <securityCode>777</securityCode>
            <processWithoutCvv2>false</processWithoutCvv2>
        </creditCard>
        <extraParameters>
            <INSTALLMENTS_NUMBER>1</INSTALLMENTS_NUMBER>
            <RESPONSE_URL>https://merchant.shoppingresult.com</RESPONSE_URL>
        </extraParameters>
        <type>AUTHORIZATION_AND_CAPTURE</type>
        <paymentMethod>MASTERCARD</paymentMethod>
        <paymentCountry>CO</paymentCountry>
        <ipAddress>45.6.10.241</ipAddress>
        <userAgent>Mozilla/5.0 (Windows; U; Windows NT 6.0) AppleWebKit/531.2.0 (KHTML, like Gecko) Chrome/21.0.885.0 Safari/531.2.0</userAgent>
        <cookie>sefejihsxeai037qhkwa3jex9</cookie>
        <deviceSessionId>cb066830a3dcbdaf7234fd230d1959b0c6b3ae3ad5265490d55802a61738b537</deviceSessionId>
        <integrationMethod>POST_API_v4_0</integrationMethod>
        <req3DSAuthentication>true</req3DSAuthentication>
        <source>WEB</source>
    </transaction>
    <test>false</test>
</request>

Testing the 3DS Authentication

To test the 3DS authentication process, use the dummy values provided in the table below. These values are applicable across the different payment methods available in each country:

	Argentina	Brazil	Colombia	Mexico	Peru
Account ID	516684	516685	516686	516687	516688
Merchant ID	508029
API Login	pRRXKOl8ikMmt9u
API Key	4Vj8eK4rloUd272L48hsrarnUA
Public Key	PKaC6H4cEDJD919n705L544kSU

Note

These account IDs are for testing purposes only, do not use them in production environments.

Test Cards

You can use the following test cards to replicate different 3DS scenarios in the test environment. Do not use these cards in production.

Brand	Card Number	3DS Scenario
Mastercard	`5521455186577727`	Card is not registered for 3DS
Mastercard	`5436062405627681`	3DS challenge required
Mastercard	`5150030090350186`	3DS successful without friction (no challenge required)
Mastercard	`5150030090050182`	3DS successful without friction (no challenge required)
Visa	`4012001037141120`	3DS challenge required
Visa	`4245757666349685`	3DS challenge required

Test Data for Approved Authorizations

Use the following parameters to simulate approved transactions in the test environment:

Include APPROVED in the cardholder name (e.g. APPROVED).
Use 777 as the CVV.
Expiration date: a month less than or equal to 05 (i.e., month < 6) and a year after the current year (for example 05/202_ — replace _ with the appropriate digit for testing).

Test Data for Declined Authorizations

Use the following parameters to simulate declined transactions in the test environment:

Include REJECTED in the cardholder name (e.g. REJECTED).
Use 666 as the CVV.
Expiration date: a month greater than or equal to 07 (i.e., month > 6) and a year after the current year (for example 07/202_ — replace _ with the appropriate digit for testing).

Note

These numbers and conventions are for sandbox testing only. Make sure to use the test Account ID, API Key and API Login provided above when executing transactions.

Transaction Response

Upon sending a payment request, you will receive a response with a "PENDING" state for the transaction. This response will also include a field within extraParameters called THREEDS_AUTH_REDIRECT_URL.

THREEDS_AUTH_REDIRECT_URL: This URL should be used to redirect the payer to complete the 3DS authentication process. The authentication process might involve challenges like entering a one-time password (OTP) received on their phone.

Response Example

In the response example below, the merchant redirects the payer to https://merch-prod.payu.com:

{
    "code": "SUCCESS",
    "error": null,
    "transactionResponse": {
        "orderId": 3344440141,
        "transactionId": "968d3f37-25aa-4fc2-86bf-0a2eee091713",
        "state": "PENDING",
        "paymentNetworkResponseCode": null,
        "paymentNetworkResponseErrorMessage": null,
        "trazabilityCode": null,
        "authorizationCode": null,
        "pendingReason": "AWAITING_THREEDS_CALLBACK",
        "responseCode": "PENDING_THREEDS_CALLBACK",
        "errorCode": null,
        "responseMessage": null,
        "transactionDate": null,
        "transactionTime": null,
        "operationDate": 1723749925205,
        "referenceQuestionnaire": null,
        "extraParameters": {
            "BANK_REFERENCED_CODE": "CREDIT",
            "THREEDS_AUTH_REDIRECT_URL": "https://merch-prod.payu.com"
        },
        "additionalInfo": {
            "paymentNetwork": "CREDIBANCO_V2",
            "rejectionType": "NONE",
            "responseNetworkMessage": null,
            "travelAgencyAuthorizationCode": null,
            "cardType": "CREDIT",
            "transactionType": "AUTHORIZATION_AND_CAPTURE"
        }
    }
}

<paymentResponse>
    <code>SUCCESS</code>
    <transactionResponse>
        <orderId>2153050798</orderId>
        <transactionId>722480e5-276e-409d-ae9e-376b801ed725</transactionId>
        <state>PENDING</state>
        <pendingReason>AWAITING_THREEDS_CALLBACK</pendingReason>
        <responseCode>PENDING_THREEDS_CALLBACK</responseCode>
        <operationDate>2024-10-24T09:09:10</operationDate>
        <extraParameters>
            <entry>
                <string>BANK_REFERENCED_CODE</string>
                <string>CREDIT</string>
            </entry>
            <entry>
                <string>THREEDS_AUTH_REDIRECT_URL</string>
                <string>https://merch-prod.payu.com</string>
            </entry>
        </extraParameters>
        <additionalInfo>
            <paymentNetwork>REDEBAN</paymentNetwork>
            <rejectionType>NONE</rejectionType>
            <cardType>CREDIT</cardType>
            <transactionType>AUTHORIZATION_AND_CAPTURE</transactionType>
        </additionalInfo>
    </transactionResponse>
</paymentResponse>

Authentication Flow

The diagram below illustrates the end-to-end process of a transaction using PayU 3DS authentication, highlighting key steps such as request submission, authentication, and response handling.

3ds

As shown in the diagram, once the payer completes the 3DS authentication (if required), PayU will receive a notification. The transaction will then be:

Completed: If the authentication is successful.
Declined: If the authentication fails.

Last modified October 21, 2025: Documentation updates (fc056f960)

PayU-Handled 3DS Authentication

Considerations

The req3DSAuthentication Parameter

Parameters for 3DS Authentication

Request Example

Testing the 3DS Authentication

Note

Test Cards

Test Data for Approved Authorizations

Test Data for Declined Authorizations

Note

Transaction Response

Response Example

Authentication Flow

The `req3DSAuthentication` Parameter