3DS 2.0
A autenticação 3DS 2.0 (3-D Secure Authentication 2.0) valida a identidade do titular do cartão durante a compra, aumentando a segurança das transações e a taxa de aprovação. Essa autenticação reduz o risco de fraude para o comprador e evita perdas por contestação para o vendedor.
Integrar 3DS
A autenticação 3DS pode ser realizada através de dois fluxos: com ou sem Challenge. O Challenge é uma etapa adicional de verificação que o comprador deve completar para confirmar sua identidade. A decisão de exigi-lo ou não depende do emissor do cartão e do perfil de risco da transação.
Para transações de baixo risco, as informações enviadas na finalização da compra são suficientes e o Challenge não é necessário. Para transações de alto risco, o Challenge é exigido para verificar a identidade do comprador, aumentando a taxa de aprovação.
Para integrar o 3DS 2.0 em Checkout API com a API de Orders, siga as etapas a seguir.
A configuração do 3DS é realizada através do nó config.online.transaction_security ao criar a order. Para criar uma order com 3DS, envie um POST ao endpoint /v1/ordersAPI incluindo seu Access Token de testeChave privada de testes da aplicação criada no Mercado Pago e que é utilizada no backend. Você pode acessá-lo através de Suas integrações > Dados da integração > Testes > Credenciais de teste.. A requisição deve conter os parâmetros obrigatórios listados abaixo.
curl --request POST \
--url https://api.mercadopago.com/v1/orders \
--header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--header 'X-Idempotency-Key: {{SOME_UNIQUE_VALUE}}' \
--data '{
"type": "online",
"external_reference": "3ds_test",
"processing_mode": "automatic",
"capture_mode": "automatic_async",
"total_amount": "150.00",
"config": {
"online": {
"transaction_security": {
"validation": "on_fraud_risk",
"liability_shift": "required"
}
}
},
"payer": {
"email": "test@testuser.com"
},
"transactions": {
"payments": [
{
"amount": "150.00",
"payment_method": {
"id": "master",
"type": "credit_card",
"token": "{{CARD_TOKEN}}",
"installments": 1
}
}
]
}
}'| Atributo | Tipo | Descrição | Valores possíveis | Obrigatoriedade |
capture_mode | String | Define o modo de captura do pagamento. | automatic_async: captura automática assíncrona.manual: captura manual. | Opcional |
config.online.transaction_security.validation | String | Define quando o fluxo de 3DS deve ser executado. | on_fraud_risk: o 3DS é exigido conforme o risco da transação. Recomendamos utilizar este valor para conciliar segurança e aprovação das transações.never: o fluxo de 3DS e o Challenge nunca são executados (este é o valor padrão se o campo não for enviado). | Obrigatório para integrações com 3DS. |
config.online.transaction_security.liability_shift | String | Define a responsabilidade financeira em caso de contestação. | required: a responsabilidade financeira em caso de contestação é da bandeira do cartão. Este é o único valor aceito para 3DS. | Obrigatório para integrações com 3DS. Não deve ser enviado quando validation for never. |
Após criar a order, a resposta indicará se o Challenge é necessário. Caso não seja exigido, o campo status trará o valor processed, permitindo que você siga normalmente com o fluxo da aplicação. Se o Challenge for necessário, a order será retornada com status: action_required, status_detail: pending_challenge, e a URL do Challenge estará disponível no campo payment_method.transaction_security.url, conforme o exemplo abaixo:
{
"id": "ORDTST01KBD0NXX289XWW91Q9NNJ26V3",
"type": "online",
"processing_mode": "automatic",
"external_reference": "ext_ref_3ds",
"total_amount": "150.00",
"total_paid_amount": "150.00",
"country_code": "ARG",
"user_id": "791690672",
"status": "action_required",
"status_detail": "pending_challenge",
"capture_mode": "automatic_async",
"currency": "ARS",
"created_date": "2025-12-01T13:12:23.202Z",
"last_updated_date": "2025-12-01T13:12:24.943Z",
"integration_data": {
"application_id": "8275829243271683"
},
"config": {
"online": {
"transaction_security": {
"validation": "on_fraud_risk",
"liability_shift": "required"
}
}
}
"transactions": {
"payments": [
{
"id": "PAY01KBD0NXX289XWW91Q9P1BF71Q",
"amount": "150.00",
"paid_amount": "150.00",
"reference_id": "0007aoefzk",
"status": "action_required",
"status_detail": "pending_challenge",
"payment_method": {
"id": "master",
"type": "credit_card",
"token": "adac6b95f1d22c51890499d1707f0f0a",
"installments": 1,
"transaction_security": {
"url": "https://www.mercadopago.com.ar/auth/card/validation/pages/remedies/019ada0a-fe1f-7a82-ba1a-1ccb4e0232e7?display_mode=self_hosted&guest_token=0661345a-e0e1-4c09-aff9-b7929ca9a24a",
"validation": "on_fraud_risk",
"liability_shift": "required"
}
}
}
]
}
}Para exibir o Challenge, crie um iframe usando a URL retornada em transactions.payments[i].payment_method.transaction_security.url. Esse iframe deve ser incorporado na página de checkout, permitindo que o comprador realize a autenticação sem sair do fluxo.
Quando o Challenge é iniciado, no momento em que a URL é criada, o comprador tem 40 minutos para completá-lo. Se não for concluído neste período, o banco recusará a transação e o Mercado Pago considerará o pagamento expirado. Caso seja necessário menos tempo, é possível realizar o cancelamento da transação antes do prazo padrão.
A atualização do status não é imediata e pode levar alguns instantes. Consulte a próxima etapa para obter mais detalhes sobre como verificar o status de cada transação.
Uma transação com 3DS pode apresentar diferentes status de acordo com o tipo de autenticação realizada, com ou sem Challenge. Para pagamentos sem Challenge, o status da transação será diretamente processed ou failed. Já em pagamentos com Challenge, a transação retorna action_required e status_detail: pending_challenge, iniciando o processo de autenticação com o banco. O status final só será exibido após a conclusão do Challenge.
Para verificar o resultado da transação após o Challenge, você pode configurar notificações Webhooks para receber alertas automáticos e redirecionar o comprador para uma tela de confirmação. Outra opção, que recomendamos, é tratar um evento iframe implementando um listener JavaScript para detectar quando o Challenge foi concluído e consultar o status da order.
Para tratar o evento iframe, siga as etapas abaixo.
- Implemente o listener para detectar quando o comprador completou o Challenge:
window.addEventListener("message", (e) => {
if (e.data.status === "COMPLETE") {
// Challenge concluído. Redirecione para a página de confirmação
window.location.href = "confirmation.html";
}
});- Utilize o código abaixo para consultar o status atualizado da order e exibi-lo na página de confirmação:
document.addEventListener("DOMContentLoaded", async function (e) {
await checkOrderStatus();
});
async function checkOrderStatus() {
const orderId = localStorage.getItem("orderId");
try {
const response = await fetch("/get_order/" + orderId, {
method: "GET",
});
const result = await response.json();
if (result.status !== 200) {
throw new Error("Erro ao consultar order");
}
// Exibir resultado
document.getElementById("order-status").innerHTML =
`Order ${result.data.id} - Status: ${result.data.status}`;
} catch (error) {
alert("Erro inesperado: " + JSON.stringify(error));
}
}Confira abaixo os principais status possíveis e suas respectivas descrições:
| Status | Status detail | Descrição |
processed | accredited | Transação aprovada sem autenticação. |
failed | failed | Transação rejeitada sem autenticação. Para verificar os motivos, consulte a documentação Status da transação. |
action_required | pending_challenge | Transação pendente de autenticação. O Challenge foi iniciado e o comprador tem até 40 minutos para completá-lo. |
failed | cc_rejected_3ds_challenge | Transação rejeitada devido a falha no Challenge. |
canceled | expired | Transação expirada. O timeout de 40 minutos do Challenge expirou sem que o comprador o completasse. É necessário criar uma nova order. |
Além do status e status_detail da transação, você também pode consultar o status específico da autenticação 3DS no campo transactions.payments[i].payment_method.transaction_security.status retornado no endpoint GET /v1/orders/{id}API, onde estão disponíveis os valores possíveis e suas descrições.
Para validar a integração com 3DS, crie uma order de teste enviando um POST ao endpoint /v1/ordersAPI incluindo seu Access Token de testeChave privada de testes da aplicação criada no Mercado Pago e que é utilizada no backend. Você pode acessá-lo através de Suas integrações > Dados da integração > Testes > Credenciais de teste. e os parâmetros obrigatórios, entre eles o nó transaction_security com validation: on_fraud_risk.
curl --request POST \
--url https://api.mercadopago.com/v1/orders \
--header 'Authorization: Bearer {{YOUR_TEST_ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--header 'X-Idempotency-Key: {{SOME_UNIQUE_VALUE}}' \
--data '{
"type": "online",
"external_reference": "3ds_test",
"processing_mode": "automatic",
"total_amount": "150.00",
"config": {
"online": {
"transaction_security": {
"validation": "on_fraud_risk",
"liability_shift": "required"
}
}
},
"payer": {
"email": "test@testuser.com"
},
"transactions": {
"payments": [
{
"amount": "150.00",
"payment_method": {
"id": "master",
"type": "credit_card",
"token": "{{CARD_TOKEN}}",
"installments": 1
}
}
]
}
}'Para testar o pagamento criado, utilize um cartão de teste, informando um dos valores abaixo no campo cardholder_name para simular diferentes fluxos do Challenge:
pending_challenge só serão retornados ao utilizar os valores APRO-CHOK ou OTHE-CHNO no campo cardholder_name. Para os demais valores, a order retornará diretamente com o status final (processed ou failed), sem passar pelo status pending_challenge.Valor de cardholder_name | Status do 3DS | Status | Status detail | Descrição |
APRO-AUTH | authenticated | processed | accredited | Challenge bem-sucedido com autenticação. |
APRO-ATMT | attempted | processed | accredited | Challenge tentado (attempted). |
OTHE-NAUT | not_authenticated | failed | failed | Sem autenticação. |
APRO-CHOK | authenticated | processed | accredited | Challenge autenticado. |
OTHE-CHNO | not_authenticated | failed | failed | Challenge não autenticado. |
APRO-foobar | not_authenticated | failed | failed | Qualquer outro valor resulta em falha. |
Nos fluxos de teste com APRO-CHOK e OTHE-CHNO, o Challenge será exibido dentro do iframe:
O código de verificação exibido é ilustrativo. Para concluir o teste, clique em Confirmar e, em seguida, consulte os possíveis status na etapa Verificar status da transação para conferir o resultado.
Após concluir a integração com 3DS e finalizar os testes, sua aplicação estará pronta para produção. Antes de continuar, confira os requisitos na documentação Subir em produção para garantir que a integração esteja apta a receber transações reais.