Passo a Passo

Abaixo um resumo do fluxo para solicitar uma venda autenticada.

Iniciar uma venda do tipo type.PAYMENT, com meio de pagamento payments.payment_methodcomo card e payments.enabled_3dscomo true

Caso tenha dúvidas sobre os tipos de vendas, verifique a seção na documentação MODELOS DE COBRANÇA.
Armazenar os dados retornados no objeto auth_3ds
1. public_key: chave para autenticar a sessão do pagamento
2. operation_url: url utilizada para redirecionar o comprador para a página do banco.

Criar um formulário para redirecionar o comprador para a página do banco.

o formulário deve conter os dados do objeto auth_3ds

<script src='https://static.payzen.eu/static/js/authenticate-client/V1.0/kr-authenticate.umd.js'></script>

<form action='javascript:authenticatePayment()'>
<button id='submitButton' type='submit' class='btn btn-primary'>Authenticate</button>
</form>

<script>
// instantiate library
const krAuthenticate = new KrAuthenticate('INSIRA A CHAVE PUBLIC_KEY');

// Main function triggered by button
function authenticatePayment() {

document.querySelector('#submitButton').disabled = true;
krAuthenticate.authenticate("URL retornada no campo operationUrl");
}
</script>

O comprador ao ser redirecionado, irá visualizar a página de autenticação do seu próprio banco. Ex.:
Após concluir ou cancelar, o processo será finalizado.

No mesmo momento em que o comprador for redirecionado, nosso sistema irá acionar um webhook para notificar que houve a primeira solicitação e criação da venda
Após o comprador finalizar a autenticação, iremos acionar um segundo webhook atualizando a venda, com as informações da transaçãoe se houve ou não autenticação e/ou autorização.

Exemplo de requisição

{
    "amount": 2000,
    "order_id": "BR0000-71203328",
    "order_info": "charge description",
    "currency": "BRL",
    "type": "PAYMENT",
    "soft_descriptor": "PAYTEST",
    "client_ip": "62.11.249.254",
    
    "payments": [
        {
            "payment_method": "card",
            "amount": 2000,
            "installments": 12,
            "create_token": false,
            "enable_3ds": true,
            "card": {
                "number": "5100010000000106",
                "exp_year": 2025,
                "exp_month": 12,
                "cvv": "1234",
                "holder_name": "Jaime Schuppe"
            }
        }
    ],
    "customer": {
        "name": "Barbara Dibbert",
        "email": "[email protected]",
        "phone": "551198570711",
        "mobile_phone": "5511985270748",
        "birth_date": "2000-01-01",
        "document_type": "CPF",
        "document_number": "62286843023"
    }
}

Exemplo de resposta

{
    "uuid": "ad516a2e-fe87-47f6-b035-f4666eead4d2",
    "type": "PAYMENT",
    "expiry_date": "2025-04-26T02:59:59Z",
    "status": "DUE",
    "order_id": "BR0000-71203328",
    "order_info": "charge description",
    "currency": "BRL",
    "original_amount": 2000,
    "amount": 2000,
    "paid": 0,
    "due": 2000,
    "refunded": 0,
    "attempts": 1,
    "max_attempts": 5,
    "drop_reason": "",
    "surcharge": false,
    "client_ip": "62.11.249.254",
    "soft_descriptor": "PAYTEST",
    "auth_3ds": {
        "public_key": "6213...:testpublickey_vSiRlWt......",
        "operation_url": "https://api.payzen.com.br/api-payment/V4/Charge/Public/Authenticate/Payment/Session/.....rod-fr-lyra",
        "operation_session_id": "ae2acab6...."
    },
    "customer": {
        "uuid": "4971d156-c923-429b-a3fc-26021ebef62d",
        "name": "Barbara Dibbert",
        "email": "[email protected]",
        "birth_date": "2000-01-01",
        "phone": "551198570711",
        "mobile_phone": "5511985270748",
        "document_type": "CPF",
        "document_number": "622******23",
        "created_at": "2025-04-23T15:39:44Z",
        "updated_at": "2025-04-23T15:39:44Z"
    },
    "transactions": [],
    "created_at": "2025-04-23T15:39:44Z",
    "updated_at": "2025-04-23T15:39:44Z"
}

Exemplo JSFiddle

Webhook da Venda Criada

Após realizado redirecionamento do comprador, será retornado o webhook com a criação da venda

{
   "uuid":"2ae86ee8-48c1-4e46-8669-fa2298d0a0c7",
   "type":"PAYMENT",
   "expiry_date":"2025-04-26T02:59:59Z",
   "status":"DUE",
   "order_id":"BR0000-95821862",
   "order_info":"charge description",
   "currency":"BRL",
   "original_amount":2000,
   "amount":2000,
   "paid":0,
   "due":2000,
   "refunded":0,
   "attempts":1,
   "max_attempts":5,
   "drop_reason":"",
   "surcharge":false,
   "client_ip":"206.114.140.113",
   "soft_descriptor":"PAYTEST",
   "customer":{
      "uuid":"94ad173f-6e69-41fe-86bc-913ba356d1af",
      "name":"Estelle Gerlach",
      "email":"[email protected]",
      "birth_date":"2000-01-01",
      "phone":"551198570711",
      "mobile_phone":"5511985270748",
      "document_type":"CPF",
      "document_number":"622******23",
      "created_at":"2025-04-23T15:53:33Z",
      "updated_at":"2025-04-23T15:53:33Z"
   },
   "transactions":[
      
   ],
   "created_at":"2025-04-23T15:53:33Z",
   "updated_at":"2025-04-23T15:53:33Z"
}

Webhook da Venda após tentativa de autenticação

Os dados referentes a autenticação serão retornados no objeto auth_3ds

{
   "uuid":"f7582171-1aee-4214-8087-41b3a90aaa71",
   "type":"PAYMENT",
   "expiry_date":"2025-04-27T02:59:59Z",
   "status":"PAID",
   "order_id":"BR0000-81247158",
   "order_info":"charge description",
   "currency":"BRL",
   "original_amount":2000,
   "amount":2000,
   "paid":2000,
   "due":0,
   "refunded":0,
   "attempts":1,
   "max_attempts":5,
   "drop_reason":"",
   "surcharge":false,
   "client_ip":"241.227.143.116",
   "soft_descriptor":"PAYTEST",
   "customer":{
      "uuid":"2da120da-8d01-41d2-b063-c804af313e1b",
      "name":"Vanessa Waters",
      "email":"[email protected]",
      "birth_date":"2000-01-01",
      "phone":"551198570711",
      "mobile_phone":"5511985270748",
      "document_type":"CPF",
      "document_number":"622******23",
      "created_at":"2025-04-24T15:33:19Z",
      "updated_at":"2025-04-24T15:33:19Z"
   },
   "transactions":[
      {
         "uuid":"abae8db0-3aa5-460d-9580-3b5251c4c979",
         "charge_uuid":"f7582171-1aee-4214-8087-41b3a90aaa71",
         "gateway_id":"fe0f9474a6b6406eba2bd361835a6897",
         "amount":2000,
         "paid_amount":2000,
         "status":"PAID",
         "payment_option":"CARD",
         "payment_option_detail":"card",
         "scheme":"VISA",
         "external_id":"00029183104392156550",
         "transaction_id_reference":null,
         "expected_capture_date":"2025-04-24T15:33:19Z",
         "payment_at":"2025-04-24T15:33:19Z",
         "captured_at":null,
         "auth_num":"031362",
         "auth_response_code":"0",
         "operation_type":"DEBIT",
         "extra":null,
         "payment_number":"497011XXXXXX1003",
         "payer_info":"",
         "expiry_month":12,
         "expiry_year":2025,
         "acquirer_network":"REDE",
         "nsu":"005432276624",
         "tid":"",
         "token":"fe09591429b842ceaab0a495d51ebf90",
         "create_token":true,
         "detailed_status":"AUTHORISED",
         "currency":"BRL",
         "document_type":"CPF",
         "document_number":"622******23",
         "installments":12,
         "sub_acquirer":1001,
         "has_auth_3ds":true,
         "auth_3ds":{
            "transaction_uuid":"abae8db0-3aa5-460d-9580-3b5251c4c979",
            "three_ds_server_id":"9b540dfc-64af-43d2-a5df-140a02e2fa87",
            "ds_trans_id":"e5d20c0a-4076-496b-b6e4-da05324e75fa",
            "acs_trans_id":"55b845f6-f188-481b-a9d0-00d8e94d3180",
            "sdk_trans_id":null,
            "eci":"05",
            "auth_type":"CHALLENGE",
            "auth_type_preference":"NO_PREFERENCE",
            "auth_type_id":"dsTransId",
            "auth_method":"CAVV",
            "status":"SUCCESS",
            "detailed_status":"",
            "detailed_status_reason":null,
            "protocol":"THREEDS",
            "version":"2.1.0",
            "network":"VISA",
            "requestor_name":"LYRA M2M",
            "challenge_cancelation_indicator":null,
            "failed_reason":null,
            "card_holder_info":null,
            "data_only_status":null,
            "data_only_decision":null,
            "data_only_score":null,
            "created_at":"2025-04-24T15:33:46Z",
            "updated_at":"2025-04-24T15:33:46Z"
         },
         "created_at":"2025-04-24T15:33:46Z",
         "updated_at":"2025-04-24T15:33:46Z"
      }
   ],
   "created_at":"2025-04-24T15:33:19Z",
   "updated_at":"2025-04-24T15:33:19Z"
}

Analisar o resultado do Autenticação

Quando uma autenticação é aprovada, o banco retorna o resultado através da lista de valores da tabela ECI.

O valor será retornado no campo auth_3ds.eci

Através do valor retornado, a decisão de prosseguir ou não com a transação deve ser tomada pelo estabelecimento com base no resultado do ECI.

Caso a transação não seja autenticada, ela ainda pode ser submetida para autorização. Contudo, nessa situação, a responsabilidade por eventuais chargebacks recai sobre o estabelecimento comercial.

Mastercard	Visa	Elo	Amex	Resultado da autenticação	A transação foi autenticada?
02	05	05	05	Autenticada pelo emissor – risco de chargeback passa a ser do emissor.	Sim
01	06	06	06	Autenticada pela bandeira – risco de chargeback passa a ser do emissor.	Sim
Diferente de 01, 02 e 04	Diferente de 05 e 06	Diferente de 05 e 06	Diferente de 05 e 06	Não autenticada – risco de chargeback permanece com o estabelecimento.	Não
04	7	-	-	Não autenticada, transação caracterizada como Data Only – risco de chargeback permanece com o estabelecimento.	Não

📘
Autenticação como "Data Only"
O Data Only é um tipo de transação no protocolo 3DS em que os dados da transação são compartilhados com o emissor, mas sem a etapa de autenticação por desafio ao portador do cartão. Esse modelo é sempre sem atrito (frictionless), ou seja, não há interrupções para o comprador durante o processo.
Esse tipo de transação pode ser útil para melhorar a base de dados do emissor e aumentar as taxas de aprovação em situações de menor risco