Executar Autenticação 3DS

A etapa de autenticação 3DS é executada inteiramente no browser por meio do SDK ZendrySDKThreeds. O SDK gerencia todo o ciclo de vida da autenticação: cria a sessão 3DS, executa o fluxo de autenticação (com ou sem desafio) diretamente no navegador do portador do cartão e retorna os dados necessários para finalizar o pagamento com 3DS.

Tipos de Autenticação

O fluxo do 3DS pode ocorrer com desafio challenge ou sem desafio/atrito frictionless. No fluxo com desafio, é exigida uma confirmação adicional do portador do cartão, como a validação via aplicativo bancário ou selfie, por exemplo, sendo essa etapa de responsabilidade do emissor. Já o fluxo frictionless autentica o usuário sem a necessidade de um desafio, retornando diretamente os dados de autenticação.

O SDK gerencia ambos os cenários automaticamente, exibindo o iframe de desafio quando necessário ou concluindo a autenticação de forma transparente quando o fluxo for frictionless.

Fluxo Resumido

O cliente gera o access_token no backend via Geração do Token de Acesso.
O cliente chama ZendrySDKThreeds.init_threeds() com token, amount e payment_form.
O cliente recebe o resultado do SDK, onde contém o operation_session_id.
Após a finalização da autenticação, o cliente deve utilizar o operation_session_id para fazer uma requisição em Resposta do Desafio 3DS e obter o resultado para finalizar o pagamento.

Como Usar o SDK no Browser

1. Carregue o SDK

 https://cdn.zendry.com/v1/zendry-sdk-threeds.min.js

2. Inicie a autenticação

<script>
  const result = await ZendrySDKThreeds.init_threeds({
    token: accessToken,
    amount: 1000,
    payment_form: {
      network_preference: 'VISA',
      account_type: 'CREDIT',
      pan: '4970115000000228',
      expiry_month: '12',
      expiry_year: '29',
      card_holder_name: 'JOHN DOE',
      installment_number: 1,
      issuer_installment: true
    }
  })

  console.log(result)
</script>

Parâmetros do init_threeds

Parâmetro	Tipo	Descrição	Obrigatório
`token`	string	Access Token Bearer gerado via `POST /auth/generate_token`	Sim
`amount`	integer	Valor do pagamento em centavos (ex.: `1000` = R$ 10,00)	Sim
`payment_form`	object	Dados do cartão e preferências de pagamento	Sim
`payment_form.network_preference`	string	Bandeira do cartão. Exemplos: `VISA`, `MASTERCARD`, `ELO`, `AMEX`	Sim
`payment_form.account_type`	string	Tipo de conta. Valores permitidos: `CREDIT`, `DEBIT`	Sim
`payment_form.pan`	string	Número do cartão, sem espaços ou traços	Sim
`payment_form.expiry_month`	string	Mês de expiração do cartão, no formato MM (ex.: `12`)	Sim
`payment_form.expiry_year`	string	Ano de expiração do cartão, no formato YY (ex.: `29`)	Sim
`payment_form.card_holder_name`	string	Nome do titular do cartão conforme impresso no cartão	Sim
`payment_form.installment_number`	integer	Número de parcelas (ex.: `1` para à vista)	Sim
`payment_form.issuer_installment`	boolean	Indica se o parcelamento é do emissor (`true`) ou do estabelecimento (`false`)	Sim

3. Callbacks

É possível acompanhar cada etapa da autenticação por meio de callbacks:

const result = await ZendrySDKThreeds.init_threeds({
  token: accessToken,
  amount: 1000,
  payment_form: {
    network_preference: 'VISA',
    account_type: 'CREDIT',
    pan: '4970115000000228',
    expiry_month: '12',
    expiry_year: '29',
    card_holder_name: 'JOHN DOE',
    installment_number: 1,
    issuer_installment: true
  },

  onSessionCreated: function (session) {
    console.log('Sessão 3DS criada', session)
  },

  onAuthenticationStart: function (event) {
    console.log('Autenticação iniciada', event)
  },

  onAuthenticationFinish: function (event) {
    console.log('Provider finalizou', event)
  },

  onGetSessionFinish: function (session) {
    console.log('Resultado oficial consultado', session)
  },

  onSuccess: function (result) {
    console.log('3DS aprovado', result.three_ds_data)
  },

  onFailure: function (result) {
    console.log('3DS recusado/não aprovado', result)
  },

  onError: function (error) {
    console.error('Erro técnico no 3DS', error)
  }
})

Retorno de cada callback

onSessionCreated

{
  "status": "SUCCESS",
  "version": "V4",
  "application_version": "6.43.10",
  "server_date": "2026-05-15T00:50:03+00:00",
  "ticket": "cb2af7b0afaa4507a1ffd1f5625e502f",
  "answer": {
    "operation_session_id": "8f250597d1964683abb21a58241468c4",
    "operation_url": "https://api.zendry.com/api-payment/V4/Charge/Public/Authenticate/Session/8f250597d1964683abb21a58241468c4",
    "provider": 2
  }
}

onAuthenticationStart

{
  "provider": 2,
  "operation_session_id": "8f250597d1964683abb21a58241468c4",
  "status": "STARTED"
}

onAuthenticationFinish

{
  "provider": 2,
  "operation_session_id": "8f250597d1964683abb21a58241468c4",
  "status": "FINISHED",
  "partner_result": {
    "status": "SUCCESS",
    "flow": "CHALLENGE"
  }
}

onGetSessionFinish

{
  "operation_session_id": "8f250597d1964683abb21a58241468c4",
  "status": "SUCCESS",
  "answer": {
    "id": "0b47b037-5360-42e2-8b61-2d95605a53b7",
    "xid": "de25ed0c-b4c6-49ec-bd69-2f8478219068",
    "eci": "02",
    "cavv": "kBMkIS6TvtjesABke//Be5hhJqAk",
    "secure_version": "2.2.0",
    "directory_server_transaction_id": "de25ed0c-b4c6-49ec-bd69-2f8478219068",
    "three_ds_server_transaction_id": "0b47b037-5360-42e2-8b61-2d95605a53b7",
    "trans_status": "SUCCESSFUL"
  }
}

onSuccess

{
  "success": true,
  "status": "SUCCESS",
  "provider": 2,
  "operation_session_id": "8f250597d1964683abb21a58241468c4",
  "threeds_flow": "CHALLENGE",
  "three_ds_data": {
    "operation_session_id": "8f250597d1964683abb21a58241468c4",
    "id": "0b47b037-5360-42e2-8b61-2d95605a53b7",
    "xid": "de25ed0c-b4c6-49ec-bd69-2f8478219068",
    "eci": "02",
    "cavv": "kBMkIS6TvtjesABke//Be5hhJqAk",
    "secure_version": "2.2.0",
    "directory_server_transaction_id": "de25ed0c-b4c6-49ec-bd69-2f8478219068",
    "three_ds_server_transaction_id": "0b47b037-5360-42e2-8b61-2d95605a53b7",
    "trans_status": "SUCCESSFUL"
  },
  "session": {
    "create_session": {
      "status": "SUCCESS",
      "version": "V4",
      "application_version": "6.43.10",
      "server_date": "2026-05-15T00:50:03+00:00",
      "ticket": "cb2af7b0afaa4507a1ffd1f5625e502f",
      "answer": {
        "operation_session_id": "8f250597d1964683abb21a58241468c4",
        "operation_url": "https://api.zendry.com/api-payment/V4/Charge/Public/Authenticate/Session/8f250597d1964683abb21a58241468c4",
        "provider": 2
      }
    },
    "get_session": {
      "operation_session_id": "8f250597d1964683abb21a58241468c4",
      "status": "SUCCESS",
      "answer": {
        "id": "0b47b037-5360-42e2-8b61-2d95605a53b7",
        "xid": "de25ed0c-b4c6-49ec-bd69-2f8478219068",
        "eci": "02",
        "cavv": "kBMkIS6TvtjesABke//Be5hhJqAk",
        "secure_version": "2.2.0",
        "directory_server_transaction_id": "de25ed0c-b4c6-49ec-bd69-2f8478219068",
        "three_ds_server_transaction_id": "0b47b037-5360-42e2-8b61-2d95605a53b7",
        "trans_status": "SUCCESSFUL"
      }
    }
  },
  "partner_result": {
    "status": "SUCCESS",
    "flow": "CHALLENGE"
  }
}

onFailure

{
  "success": false,
  "status": "REJECTED",
  "provider": 2,
  "operation_session_id": "8f250597d1964683abb21a58241468c4",
  "threeds_flow": "CHALLENGE",
  "error": {
    "code": "REJECTED",
    "message": "Authentication rejected",
    "detail": "Authentication was rejected by ACS"
  },
  "session": {
    "create_session": {
      "status": "SUCCESS",
      "answer": {
        "operation_session_id": "8f250597d1964683abb21a58241468c4",
        "operation_url": "https://api.zendry.com/api-payment/V4/Charge/Public/Authenticate/Session/8f250597d1964683abb21a58241468c4",
        "provider": 2
      }
    },
    "get_session": {
      "operation_session_id": "8f250597d1964683abb21a58241468c4",
      "status": "REJECTED",
      "answer": {
        "trans_status": "REJECTED"
      }
    }
  },
  "partner_result": {
    "status": "REJECTED"
  }
}

onError

{
  "message": "Failed to load script: vendor/kr-authenticate.umd.js",
  "response": null
}

ou:

{
  "message": "web-service input data validation error",
  "response": {
    "status": "ERROR",
    "version": "V4",
    "application_version": "6.43.10",
    "server_date": "2026-05-15T00:38:40+00:00",
    "ticket": "5110c09d79b448d48807b67434a4c6d6",
    "answer": {
      "error_code": "INT_902",
      "error_message": "web-service input data validation error",
      "detailed_error_message": "Input value not defined [name=recurring.expiryDate]"
    }
  }
}

Retorno final da Promise

Se aprovado:

{
  "success": true,
  "status": "SUCCESS",
  "provider": 2,
  "operation_session_id": "8f250597d1964683abb21a58241468c4",
  "threeds_flow": "CHALLENGE",
  "three_ds_data": {
    "operation_session_id": "8f250597d1964683abb21a58241468c4",
    "id": "0b47b037-5360-42e2-8b61-2d95605a53b7",
    "xid": "de25ed0c-b4c6-49ec-bd69-2f8478219068",
    "eci": "02",
    "cavv": "kBMkIS6TvtjesABke//Be5hhJqAk",
    "secure_version": "2.2.0",
    "directory_server_transaction_id": "de25ed0c-b4c6-49ec-bd69-2f8478219068",
    "three_ds_server_transaction_id": "0b47b037-5360-42e2-8b61-2d95605a53b7",
    "trans_status": "SUCCESSFUL"
  }
}

Se não aprovado:

{
  "success": false,
  "status": "FAILED",
  "provider": 2,
  "operation_session_id": "8f250597d1964683abb21a58241468c4",
  "threeds_flow": "CHALLENGE",
  "error": {
    "code": "FAILED",
    "message": "Authentication failed"
  }
}

Sucesso

Após a execução do SDK, o resultado é retornado em um objeto que contém a propriedade operation_session_id, necessária para consultar o resultado da autenticação 3DS.

Resposta de Sucesso
{
"status": "SUCCESS",
"version": "V4",
"application_version": "6.43.10",
"server_date": "2026-05-15T00:50:03+00:00",
"ticket": "cb2af7b0afaa4507a1ffd1f5625e502f",
"answer": {
  "operation_session_id": "8f250597d1964683abb21a58241468c4",
  "operation_url": "https://api.zendry.com.br/api-payment/V4/Charge/Public/Authentica",
  "provider": 2
  }
}

Erros

Em caso de erro na autenticação, o SDK retorna um objeto com detalhes do erro.

Resposta de Erro
{
"status": "ERROR",
"version": "V4",
"application_version": "6.43.10",
"server_date": "2026-05-15T00:38:40+00:00",
"ticket": "5110c09d79b448d48807b67434a4c6d6",
"answer": {
  "error_code": "INT_902",
  "error_message": "web-service input data validation error",
  "detailed_error_message": "Input value not defined [name=recurring.expiryDate]"
  }
}

Tipos de Autenticação​

Fluxo Resumido​

Como Usar o SDK no Browser​

1. Carregue o SDK​

2. Inicie a autenticação​

3. Callbacks​

Retorno de cada callback​

Retorno final da Promise​

Sucesso​

Erros​