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.

Atenção

O fluxo de autenticação 3DS aceita somente cartões Visa, Mastercard e Elo. Cartões American Express (Amex) não são suportados neste fluxo. Oriente o cliente a utilizar uma das bandeiras aceitas.

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.

Instalação

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

Os exemplos usam a versão 1.1.0, que adiciona suporte a card_id na entrada de authenticate(). Fixe a versão para escolher quando seu checkout recebe uma atualização do SDK.

CDN

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

<script src="https://cdn.marlim.co/3ds/1.1.0/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 --save-exact marlim-sdk-3ds@1.1.0

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

Atualizações do SDK

Mantenha a versão exata na URL da CDN ou na dependência do projeto (1.1.0, sem ^ ou ~) e versione o arquivo de lock. Para atualizar, escolha a nova versão, valide seu checkout em Sandbox e altere a referência usada na integração. Publicar uma nova versão do SDK não altera uma referência fixada.

A URL legada https://cdn.marlim.co/marlim-3ds-sdk.min.js não seleciona uma versão. Para controlar as atualizações do seu checkout, migre para a URL com versão apresentada acima.

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.

Response Object

Retorno de GET /v3/3ds/sessions:

Propriedade	Tipo	Descrição
session	object	Dados da sessão utilizada pelo SDK 3DS.
session.session_token	string	Token usado para inicializar o SDK e autenticar as chamadas de setup e autenticação 3DS.
session.created_at	number	Data de criação da sessão em timestamp Unix, em milissegundos.
session.expires_at	number	Data de expiração da sessão em timestamp Unix, em milissegundos. A sessão tem validade de 30 minutos.
card_hash	object	Dados da chave pública para criptografar o cartão.
card_hash.public_key	string	Chave pública utilizada para gerar o card_hash.
card_hash.public_key_id	string	Identificador da chave pública.
card_hash.created_at	number	Data de criação da chave em timestamp Unix, em milissegundos.
card_hash.expires_at	number	Data de expiração da chave em timestamp Unix, em milissegundos.

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
  }
}

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.

Informe exatamente uma opção de cartão: card, card_hash ou card_id. Com card_id, o SDK utiliza um cartão já salvo e executa normalmente o setup, a coleta de dispositivo e uma nova autenticação 3DS. Não é necessário reenviar os dados do cartão.

Os dados do cartão devem seguir os formatos descritos em Criar Cartão, inclusive quando enviados em um card_hash.

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. Use somente quando não informar card_hash ou card_id.
card[number]	string	Número do cartão.
card[expiration_date]	string	Data de validade do cartão. Somente números no formato MMAA.
card[cvv]	string	Código verificador do cartão.
card[holder_name]	string	Nome do portador do cartão. Deve conter apenas letras e espaços, sem acentuação ou caracteres especiais.
customer	object	Objeto Cliente.
customer[name]	string	Nome do cliente.
customer[document_number]	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][country_code]	string	Código do país do telefone do cliente (DDI), Ex: 55.
customer[phone][area_code]	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. O soft_descriptor_challenge permite definir o nome exibido ao portador durante o desafio 3DS. Quando não informado, será utilizado o nome padrão configurado para o seller. Este parâmetro altera apenas o nome enviado para o 3DS (merchantName) e não substitui o soft_descriptor utilizado no endpoint de transação.

Importante

Informe exatamente uma das três opções: card, card_hash ou card_id. Não combine essas formas na mesma chamada.

Atributo	Tipo	Descrição
card_id	string	ID de um cartão já salvo na Marlim. Alternativa a card e card_hash, disponível em Sandbox e Produção.
card_hash	string	Hash de um cartão criptografado manualmente usando uma chave pública.
challenge	boolean	Força o desafio 3DS durante a autenticação. *Disponível apenas em ambiente Sandbox* para simular diferentes fluxos de autenticação.
soft_descriptor_challenge	string	Nome exibido no desafio 3DS. *Parâmetro opcional. Máximo de 30 caracteres*, aceitando letras, números e espaços. Quando não informado, utiliza o nome padrão do seller.

Exemplos de autenticação

Cada exemplo contém a chamada completa de authenticate(). Os dados do cliente e os demais parâmetros são iguais; muda apenas a forma de informar o cartão. Os valores são ilustrativos e devem ser substituídos pelos dados da sua integração.

🕹 Exemplo de autenticação com card (dados abertos)

Informe os dados do cartão no objeto card.

await MarlimSDK_3DS.authenticate({
  amount: 1000, // Valor em centavos
  soft_descriptor_challenge: 'LOJA EXEMPLO', // Opcional
  // challenge: true, // Opcional: força o desafio apenas no Sandbox
  card: {
    number: '4111111111111111',
    expiration_date: '1230', // Formato MMAA
    cvv: '123',
    holder_name: 'Jose Silva'
  },
  customer: {
    name: 'Jose Silva',
    document_number: '12345678909',
    email: 'jose.silva@example.com',
    phone: {
      number: '999999999',
      area_code: '11',
      country_code: '55'
    },
    address: {
      country: 'BR',
      state: 'SP',
      city: 'São Paulo',
      neighborhood: 'Centro',
      number: '123',
      street: 'Rua das Flores',
      zipcode: '01001000',
      complement: 'Apto 123'
    }
  }
});

🕹 Exemplo de autenticação com card_hash (cartão criptografado)

Substitua SEU_CARD_HASH pelo hash gerado para esta tentativa. Consulte como gerar um card_hash.

await MarlimSDK_3DS.authenticate({
  amount: 1000, // Valor em centavos
  soft_descriptor_challenge: 'LOJA EXEMPLO', // Opcional
  // challenge: true, // Opcional: força o desafio apenas no Sandbox
  card_hash: 'SEU_CARD_HASH',
  customer: {
    name: 'Jose Silva',
    document_number: '12345678909',
    email: 'jose.silva@example.com',
    phone: {
      number: '999999999',
      area_code: '11',
      country_code: '55'
    },
    address: {
      country: 'BR',
      state: 'SP',
      city: 'São Paulo',
      neighborhood: 'Centro',
      number: '123',
      street: 'Rua das Flores',
      zipcode: '01001000',
      complement: 'Apto 123'
    }
  }
});

🕹 Exemplo de autenticação com card_id (cartão salvo)

Substitua o card_id pelo ID de um cartão já salvo no ambiente utilizado (Sandbox ou Produção). Não é necessário reenviar os dados do cartão nem gerar um card_hash.

await MarlimSDK_3DS.authenticate({
  amount: 1000, // Valor em centavos
  soft_descriptor_challenge: 'LOJA EXEMPLO', // Opcional
  // challenge: true, // Opcional: força o desafio apenas no Sandbox
  card_id: 'card_097v98z0djvnbwaaaai54mxqew',
  customer: {
    name: 'Jose Silva',
    document_number: '12345678909',
    email: 'jose.silva@example.com',
    phone: {
      number: '999999999',
      area_code: '11',
      country_code: '55'
    },
    address: {
      country: 'BR',
      state: 'SP',
      city: 'São Paulo',
      neighborhood: 'Centro',
      number: '123',
      street: 'Rua das Flores',
      zipcode: '01001000',
      complement: 'Apto 123'
    }
  }
});

O setup reutiliza o card_id informado. Com card ou card_hash, ele cria um novo identificador. Em todos os casos, use os IDs retornados para esta tentativa e informe o mesmo valor na transação. Reutilizar o cartão não permite reutilizar uma autenticação anterior.

Response Object

Propriedade	Tipo	Descrição
card_id	string	ID do cartão retornado pelo setup. É o mesmo informado na entrada com card_id.
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.

SDK​

Instalação​

CDN​

NPM​

Atualizações do SDK​

Token de sessão​

Chave pública para criptografia​

Response Object​

Inicialização​

Autenticação​

Propriedades​

Opcionais​

Exemplos de autenticação​

Response Object​

SDK

Instalação

CDN

NPM

Atualizações do SDK

Token de sessão

Chave pública para criptografia

Response Object

Inicialização

Autenticação

Propriedades

Opcionais

Exemplos de autenticação

Response Object