Integração com 3DS

A Marlim utiliza a autenticação 3D Secure (3DS) para confirmar a identidade do portador do cartão durante o pagamento. Quando o 3DS é acionado, o banco emissor pode pedir um passo extra de verificação. Isso reduz fraude e aumenta a taxa de aprovação das transações.

APENAS AMBIENTE DE SANDBOX

O 3DS encontra-se apenas disponível para o ambiente de sandbox. Para obter informações sobre o cronograma de disponibilização desta funcionalidade, entre em contato com o time da Marlim através dos nossos canais de suporte.

SDK

O SDK 3DS da Marlim foi desenvolvido pensando em agilizar a integração e reduzir a complexidade. Feito com objetivo de ser simples e direto, você configura, autentica e está pronto para realizar uma transação com autenticação 3DS.

Token de sessão

O primeiro passo para usar o SDK 3DS da Marlim, você precisa gerar um token de sessão através da nossa API. Este token é obrigatório para inicializar o SDK e realizar a autenticação 3DS. O token de sessão funciona como uma chave temporária que permite ao SDK se comunicar com nossos serviços de forma segura durante o processo de autenticação. Sem ele, não é possível prosseguir com a integração.

Importante

O token de sessão deve ser gerado pelo seu backend para não expor sua api_key no frontend. Nunca faça chamadas diretas para nossa API de geração de token a partir do cliente, pois isso comprometeria a segurança da sua integração.

Chave pública para criptografia

Além do token de sessão, nossa API também retorna uma chave pública necessária para criptografar os dados do cartão antes de enviá-los para autenticação 3DS.

Com essa chave pública, você poderá gerar um card_hash seguro para enviar os dados do cartão durante a autenticação 3DS. Para entender como criar o card_hash, consulte nossa documentação sobre como gerar um card_hash.

Exemplo - Gerando sessão 3DS

curl -X GET "https://api.marlim.co/v3/3ds/sessions" \
-H "api_key: sua-api-key" \
-d '{}'

Response200

{
  "session": {
    "session_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "created_at": 1760984954000,
    "expires_at": 1760986754000
  },
  "card_hash": {
    "public_key": "-----BEGIN PUBLIC KEY-----\n...",
    "public_key_id": "061ab8ee28bfb5fa...",
    "created_at": 1760984954894,
    "expires_at": 1760986754894
  }
}

Instalação

Antes de inicializar o 3DS é preciso realizar a importação do SDK via CDN ou NPM.

CDN

Para importar via CDN, adicione a tag script no seu HTML da página de checkout:

<script src="https://cdn.marlim.co/marlim-3ds-sdk.min.js"></script>

NPM

Se preferir gerenciar o SDK como dependência do seu projeto, você pode instalá-lo via NPM. Execute o comando abaixo no terminal do seu projeto:

npm install marlim-sdk-3ds

Para mais informações sobre o pacote NPM, consulte a página oficial no NPM.

Inicialização

A inicialização serve para configurar o SDK com o ambiente que você está utilizando e o token de sessão necessário para autenticação.

MarlimSDK_3DS.init({
  token: 'seu-token-de-sessao-aqui',
  env: 'sandbox' // ou 'production'
});

Importante

Este passo é fundamental para que a autenticação 3DS aconteça. Sem a inicialização correta do SDK, não será possível prosseguir com o processo de autenticação.

Autenticação

Após a inicialização do SDK, realize a autenticação 3DS utilizando o método authenticate(). Este processo coleta os dados do cartão e cliente, executa a verificação 3DS e retorna o card_id e o threeds_authentication_id.

await MarlimSDK_3DS.authenticate({
  amount: 1000, // Valor em centavos
  card: {
    number: '1111111111111111',
    expirationDate: '0126', // Formato MMAA
    cvv: '123',
    holderName: 'John Doe'
  },
  customer: {
    name: 'Jose Silva',
    documentNumber: '9999999999',
    email: 'joao.silva@example.com',
    phone: {
      number: '999999999',
      areaCode: '99',
      countryCode: '55'
    },
    address: {
      country: 'BR',
      state: 'SP',
      city: 'São Paulo',
      neighborhood: 'Centro',
      number: '123',
      street: 'Rua das Flores',
      zipcode: '01001000',
      complement: 'Apto 123'
    }
  }
});

Propriedades

Atributo	Tipo	Descrição
amount	int32	Valor final a ser cobrado do cliente pagador. Deve ser passado em centavos.
card	object	Objeto com os dados do cartão.
card[number]	string	Número do cartão.
card[expirationDate]	string	Data de validade do cartão. Somente números no formato MMAA.
card[cvv]	string	Código verificador do cartão.
card[holderName]	string	Nome do portador do cartão.
customer	object	Objeto Cliente.
customer[name]	string	Nome do cliente.
customer[documentNumber]	string	Número do documento do cliente.
customer[email]	string	E-mail do cliente.
customer[phone]	object	Objeto número do telefone do cliente.
customer[phone][countryCode]	string	Código do país do telefone do cliente (DDI), Ex: 55.
customer[phone][areaCode]	string	Código do estado do telefone do cliente (DDD).
customer[phone][number]	string	Número do telefone do cliente.
customer[address]	object	Objeto Endereço do Cliente da fatura do cartão ou residência do cliente.
customer[address][country]	string	Nacionalidade do cliente, no formato sigla do país. Só serão aceitos o formato ISO 3166-1 alfa-2 (duas-letras) Ex: BR, US, UY... Máximo em caracteres: 2
customer[address][state]	string	UF da fatura do cartão ou residência do cliente, no formato sigla do estado. Ex: SP, RJ, MG... Máximo em caracteres: 2
customer[address][city]	string	Cidade da fatura do cartão ou residência do cliente. Máximo em caracteres: 50
customer[address][neighborhood]	string	Bairro da fatura do cartão ou residência do cliente. Máximo em caracteres: 45
customer[address][street]	string	Rua da fatura do cartão ou residência do cliente. Máximo em caracteres: 54
customer[address][number]	string	Número da fatura do cartão ou residência do cliente. Máximo em caracteres: 5
customer[address][complement]	string	Parâmetro opcional do complemento da fatura do cartão ou residência do cliente. Máximo em caracteres: 14
customer[address][zipcode]	string	CEP da fatura do cartão ou residência do cliente. Máximo em caracteres: 9

Opcionais

Além dos parâmetros obrigatórios, o método authenticate() oferece parâmetros opcionais. O card_hash é uma alternativa segura aos dados abertos do cartão, permitindo identificar o cartão sem expor informações sensíveis através de um hash gerado pela nossa API de chaves públicas, consulte nossa documentação sobre como gerar um card_hash. O challenge força a exibição do desafio 3DS durante o desenvolvimento, permitindo testar diferentes cenários de autenticação.

Importante

Não é possível utilizar dados do cartão abertos e o card_hash simultaneamente. Você deve escolher somente uma das duas opções.

Atributo	Tipo	Descrição
card_hash	string	Hash do cartão criptografado. Permite identificar o cartão de forma segura sem armazenar os dados sensíveis.
challenge	boolean	Força o desafio 3DS durante a autenticação. Disponível apenas em ambiente Sandbox para simular diferentes fluxos de autenticação.

Exemplo com parâmetros opcionais

await MarlimSDK_3DS.authenticate({
  amount: 1000, // Valor em centavos
  card_hash: "93237fb4c0948881dc99929899f6eda2...",
  challenge: true, // Força desafio 3DS (apenas Sandbox)
  customer: {
    name: 'Jose Silva',
    documentNumber: '9999999999',
    email: 'joao.silva@example.com',
    phone: {
      number: '999999999',
      areaCode: '99',
      countryCode: '55'
    },
    address: {
      country: 'BR',
      state: 'SP',
      city: 'São Paulo',
      neighborhood: 'Centro',
      number: '123',
      street: 'Rua das Flores',
      zipcode: '01001000',
      complement: 'Apto 123'
    }
  }
});

Resultado

Propriedade	Tipo	Descrição
card_id	string	ID de um cartão salvo e já validado para poder utilizar na transação.
threeds_authentication_id	string	ID da autenticação 3DS. Necessário para ser enviado no endpoint de transação para que a transação ocorra com a autenticação 3DS.

Exemplo de Response

{
  "card_id": "card_097v98z0djvnbwaaaai54mxqew",
  "threeds_authentication_id": "32WcjjJ8U445AUaaaafv01"
}

Após a autenticação 3DS bem-sucedida, utilize o card_id e o threeds_authentication_id no endpoint de transação. O card_id representa um cartão salvo e já validado, podendo ser utilizado em transações futuras sem precisar informar novamente os dados do cartão. O threeds_authentication_id é obrigatório para aplicar a autenticação 3DS na transação e é específico para cada transação.

Para criar a transação, consulte nossa documentação sobre como criar uma transação com cartão.