O 3-D Secure com autenticador externo (MPI - Merchant Plug-In) é uma variação do fluxo padrão de autenticação que permite ao lojista ou à plataforma de pagamentos delegar a comunicação com o Directory Server (DS) e o ACS (Access Control Server) a um componente externo especializado.
O MPI é um módulo (geralmente fornecido pelo seu gateway ou PSP) responsável por construir, assinar e enviar as mensagens de autenticação 3DS (EMV 3-DS) ao Directory Server da bandeira, além de receber e tratar as respostas.
Se você não quer lidar com a complexidade de autenticação, recomendamos usar 3DS2 Malga.
Basta enviar os dados de 3DS e adicioná-los no campo threeDSecure2.mpi
.
Exemplo de requisição
curl --request POST 'https://api.malga.io/v1/charges' \
--header 'x-client-id: <SEU_CLIENT_ID>' \
--header 'x-api-key: <SEU_API_KEY>' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
"merchantId": "<MERCHANT_ID>",
"amount": 150, // valor em centavos: R$ 1,50
"statementDescriptor": "Teste 3DS – Adyen",
"capture": true,
"paymentMethod": {
"paymentType": "credit",
"installments": 1
},
"paymentSource": {
"sourceType": "card",
"card": {
"cardNumber": "4111111111111111",
"cardCvv": "123",
"cardExpirationDate": "12/2030",
"cardHolderName": "John Smith"
}
},
"threeDSecure2": {
"redirectURL": "https://www.sualoja.com.br/checkout",
"browser": {
"userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36",
"acceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
"language": "pt-BR",
"colorDepth": 24,
"screenHeight": 1080,
"screenWidth": 1920,
"timeZoneOffset": "180",
"javaEnabled": false,
"javaScriptEnabled": true,
"ip": "203.0.113.45"
},
"mpi": {
"acsTransactionId": "9502fcb2-f483-4e4f-b9c9-70e01d8f49e2",
"threeDSServerTransactionId": "4830a4b7-b80e-4eeb-bff2-d21699e771f0",
"directoryServerTransactionId": "4e8567db-2f9e-4c9d-9d8c-3da3c2f7ed32",
"version": "2.2.0",
"transStatus": "Y",
"cavv": "AAIBBYNoEwAAACcKhAJkdQAAAAA=",
"xid": "AAIBBYNoEwAAACcKhAJkdQAAAAA=",
"eci": "05",
"challenged": true
}
}
}'
Observe que, nesse fluxo, você não receberá um desafio (challenge), apenas o resultado final da autorização.
Recomendamos consultar a lista de provedores compatíveis com 3DS2 na Malga, pois apenas esses provedores oferecem suporte à autenticação via MPI.
Sobre os campos que precisam ser enviados
- threeDSecure2.mpi.acsTransactionId:
ID da transação gerado pelo Access Control Server (ACS) do emissor do cartão. Serve para identificar a autenticação no sistema do banco.
- threeDSecure2.mpi.threeDSServerTransactionId:
ID da transação gerado pelo 3DS Server, que é quem inicia e gerencia o fluxo de autenticação 3DS (geralmente operado pela adquirente ou subadquirente).
- threeDSecure2.mpi.directoryServerTransactionId:
ID gerado pelo Directory Server, que é o serviço da bandeira (como Visa ou Mastercard) que faz o roteamento da autenticação para o emissor do cartão.
- threeDSecure2.mpi.version:
Versão do protocolo 3D Secure utilizada na autenticação. A
"2.2.0"
é uma versão atual que permite suporte a mais casos, como autenticação por app ou biometria.
- threeDSecure2.mpi.transStatus:
Status da autenticação.
"Y"
indica que a autenticação foi realizada com sucesso. Outros valores possíveis: "N"
(falha), "U"
(inconclusiva), "A"
(tentativa).
- threeDSecure2.mpi.cavv (Cardholder Authentication Verification Value):
Valor criptográfico gerado pelo emissor que comprova que a autenticação foi feita. Ele é usado para validar a transação junto à bandeira/adquirente.
- threeDSecure2.mpi.xid:
Identificador da transação de autenticação. Em 3DS2, pode ser o mesmo valor do CAVV. É utilizado para rastreabilidade da autenticação.
- threeDSecure2.mpi.eci:
Electronic Commerce Indicator. Indica o nível de segurança da transação. O valor
"05"
normalmente significa que a autenticação foi feita com sucesso (Visa/Mastercard).
- threeDSecure2.mpi.challenged:
Indica se o portador foi desafiado durante o processo de autenticação.
true
significa que houve interação do usuário (ex: digitar senha, biometria). false
indica que a autenticação foi feita de forma silenciosa (frictionless).