Autenticação 3DS Realizada pela PayU

A autenticação 3DS realizada pela PayU evita que você precise gerenciar o processo de integração 3DS. A PayU cuida de tudo, desde a comunicação com o banco emissor até o gerenciamento do fluxo de autenticação.

Para habilitar a autenticação 3DS, entre em contato com seu representante PayU ou suporte técnico. Uma vez habilitada, inclua o parâmetro req3DSAuthentication nas suas solicitações de pagamento usando a API de Pagamentos da PayU.

Notas

A autenticação 3DS com a PayU Latam está disponível apenas na Argentina, Brasil, Colômbia, México e Peru.
Se você utiliza uma integração WebCheckout, entre em contato com seu representante da PayU ou com o suporte técnico para confirmar se a autenticação 3DS está disponível para suas transações.
Redes suportadas: Visa e Mastercard.

Parâmetro `req3DSAuthentication`

Este parâmetro permite especificar se uma transação requer autenticação 3DS. O parâmetro suporta os seguintes valores:

"true": Exige autenticação 3DS para a transação.
"false": Desativa a autenticação 3DS para a transação.

Se sua solicitação não incluir req3DSAuthentication, o motor de risco da PayU determinará se a transação requer autenticação 3DS com base na sua avaliação de risco.

Parâmetros para Autenticação 3DS

A tabela abaixo descreve os principais parâmetros associados à autenticação 3DS. Para uma lista completa de parâmetros aplicáveis a transações com cartão de crédito ou débito, consulte a documentação da API de Pagamentos do seu país.

Nome do Campo	Formato	Tamanho	Descrição
`transaction > req3DSAuthentication`	Booleano	4-5 caracteres	Especifica se a autenticação 3DS é exigida (`true` ou `false`). Se omitido, o motor de risco da PayU decide se a autenticação é necessária.
`transaction > order > notifyUrl`	Alfanumérico	Até 255 caracteres	URL de webhook que sua integração utiliza para receber o status final da transação (por exemplo, aprovada ou rejeitada) da PayU. Para uma lista detalhada de possíveis status, consulte a documentação de códigos de resposta.
`transaction > extraParameters > RESPONSE_URL`	Alfanumérico	Até 255 caracteres	URL para onde a integração redireciona o usuário após a autenticação, geralmente o site do comerciante. Se omitido, a integração redireciona o usuário para a página padrão de status de transação da PayU. Para uma lista detalhada de possíveis status, consulte a documentação de códigos de resposta.

Exemplo de uma Solicitação

No exemplo de solicitação a seguir, req3DSAuthentication está definido como true para exigir autenticação 3DS:

Exemplo de uma Solicitação:

{
    "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
}

Exemplo de uma Solicitação:

<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>

Testando a Autenticação 3DS

Para testar o processo de autenticação 3DS, utilize os valores fictícios fornecidos na tabela abaixo. Esses valores são aplicáveis aos diferentes métodos de pagamento disponíveis em cada país:

	Argentina	Brasil	Colômbia	México	Peru
Account ID	516684	516685	516686	516687	516688
Merchant ID	508029
API Login	pRRXKOl8ikMmt9u
API Key	4Vj8eK4rloUd272L48hsrarnUA
Public Key	PKaC6H4cEDJD919n705L544kSU

Nota

Esses IDs de conta são apenas para fins de teste, não os utilize em ambientes de produção.

Resposta da Transação

Ao enviar uma solicitação de pagamento, você receberá uma resposta com o estado "PENDING" para a transação. Essa resposta também incluirá um campo em extraParameters chamado THREEDS_AUTH_REDIRECT_URL.

THREEDS_AUTH_REDIRECT_URL: Essa URL deve ser usada para redirecionar o pagador para concluir o processo de autenticação 3DS. O processo de autenticação pode envolver desafios como inserir uma senha única (OTP) recebida em seu telefone.

Exemplo de uma Resposta

No exemplo de resposta abaixo, o lojista redireciona o pagador para https://merch-prod.payu.com:

Exemplo de uma Resposta:

{
    "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"
        }
    }
}

Exemplo de uma Resposta:

<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>

Fluxo de Autenticação

O diagrama abaixo ilustra o processo completo de uma transação utilizando a autenticação 3DS da PayU, destacando etapas-chave como envio da solicitação, autenticação e gerenciamento da resposta.

3dsflow_pt.html

Conforme mostrado no diagrama, assim que o pagador concluir a autenticação 3DS (se necessário), a PayU receberá uma notificação. A transação será então:

Concluída: Se a autenticação for bem-sucedida.
Recusada: Se a autenticação falhar.

Redirecionamento Após a Autenticação

Após o redirecionamento do pagador da THREEDS_AUTH_REDIRECT_URL, ele será direcionado para:

Página de status da transação do Checkout PayU: Por padrão, esse é o comportamento se o lojista não tiver especificado uma URL de retorno personalizada.
URL de retorno personalizada do lojista: Se fornecida, o pagador será redirecionado para a página designada do lojista após a autenticação.

Última modificação 14 de abril de 2025: Documentation updates (7251cd88e)