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.

Considerações

  • A autenticação 3DS com a PayU Latam está disponível apenas na Argentina, Brasil, Colômbia, México e Peru.
  • Ao utilizar autenticação 3DS em integrações via API, definir um RESPONSE_URL é obrigatório. Se não for fornecido, a transação retornará um erro.
  • 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 a qual o usuário é redirecionado após concluir a autenticação 3DS, normalmente uma página no site do lojista. Para integrações via API, este parâmetro é obrigatório. Se não for informado, a transação pode falhar, pois a PayU não conseguirá redirecionar o usuário após o desafio de autenticação. 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:


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

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

Cartões de teste

Você pode utilizar os seguintes cartões de teste para reproduzir diferentes cenários 3DS no ambiente de testes. Não use esses cartões em produção.

Bandeira Número do cartão Cenário 3DS
Mastercard 5521455186577727 O cartão não está registrado no 3DS
Mastercard 5436062405627681 Desafio 3DS necessário
Mastercard 5150030090350186 3DS bem-sucedido sem fricção (não requer desafio)
Mastercard 5150030090050182 3DS bem-sucedido sem fricção (não requer desafio)
Visa 4012001037141120 Desafio 3DS necessário
Visa 4245757666349685 Desafio 3DS necessário

Dados de teste para autorizações aprovadas

Use os seguintes parâmetros para simular transações aprovadas no ambiente de testes:

  • Inclua APPROVED no nome do titular do cartão (ex.: APPROVED).
  • Use 777 como o CVV.
  • Data de validade: um mês menor ou igual a 05 (ou seja, mês < 6) e um ano posterior ao atual (por exemplo, 05/202_ — substitua _ pelo dígito correspondente nos testes).

Dados de teste para autorizações rejeitadas

Use os seguintes parâmetros para simular transações rejeitadas no ambiente de testes:

  • Inclua REJECTED no nome do titular do cartão (ex.: REJECTED).
  • Use 666 como o CVV.
  • Data de validade: um mês maior ou igual a 07 (ou seja, mês > 6) e um ano posterior ao atual (por exemplo, 07/202_ — substitua _ pelo dígito correspondente nos testes).

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:


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

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

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.
Última modificação 21 de outubro de 2025: Documentation updates (fc056f960)