Autenticação 3DS Realizada pela PayU
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 |
Nota
Esses IDs de conta são apenas para fins de teste, não os utilize em ambientes de produção.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).
Nota
Esses números e convenções são apenas para testes em ambiente sandbox. Certifique-se de usar oAccount ID
, API Key
e API Login
de teste fornecidos acima ao executar as transações.
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.
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.