SDK 3DS 1.1.0

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.

Guia completo do SDK 1.1.0. Esta página reúne instalação, sessão, parâmetros, exemplos, retorno e alterações da versão.

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 autenticados neste fluxo.

Nesta versão, o fluxo AMEX mantém o comportamento anterior da API, incluindo os erros de configuração existentes. O SDK não retorna um resultado de dispensa.

SDK

O SDK 3DS da Marlim foi desenvolvido pensando em agilizar a integração e reduzir a complexidade. Você inicializa o SDK, chama authenticate() e trata o resultado antes de criar a transação. O SDK executa o fluxo de autenticação para as bandeiras suportadas.

Versões do SDK

Cada versão possui seu guia completo e as próprias notas de alterações na mesma página. Os parâmetros e exemplos abaixo correspondem à versão indicada no início deste guia.

Versão	Entrada do cartão	Particularidades	Documentação completa
1.0.9 — legado	card ou card_hash	Retorna os IDs string e não aceita cartão salvo como entrada.	1.0.9
1.1.0	Acrescenta card_id	Autenticação com cartão salvo e melhoria das mensagens de erro.	1.1.0
1.1.1	Mesmo contrato da 1.1.0	Correções de apresentação do desafio.	1.1.1
1.2.0	Mesmo contrato de entrada da 1.1.x	Dispensa AMEX com ID nulo e threeds_response, com API compatível.	1.2.0

As versões acima identificam os pacotes do SDK. A instalação informa a versão exata do npm e o endereço disponível na CDN. Os endpoints continuam sendo /v3/3ds/*; publicar um SDK não atualiza a versão fixada no checkout nem substitui a implantação da API.

Instalação

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

Os comandos e endereços abaixo fixam a versão 1.1.0. Escolha CDN ou npm e mantenha a versão exata na integração.

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, sem ^ ou ~, e versione o arquivo de lock. Publicar uma nova versão do SDK não altera uma referência fixada.

Para atualizar, escolha a nova versão, siga as instruções de instalação e migração do respectivo guia completo, valide seu checkout em Sandbox e altere a referência usada na integração.

Compatibilidade entre API, SDK e checkout

Os endpoints usados pelo SDK são /v3/3ds/*. Utilize os parâmetros e trate o retorno conforme a versão instalada no checkout.

Para Visa, Mastercard e Elo, o resultado contém os IDs do cartão e da autenticação como string. Esta versão mantém o comportamento AMEX anterior, incluindo os erros existentes. Para utilizar a dispensa, atualize para o SDK 1.2.0 e adapte o checkout ao resultado descrito no respectivo guia.

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 instalação via npm utiliza import MarlimSDK_3DS from 'marlim-sdk-3ds'. Ao carregar o script da CDN, utilize o objeto global MarlimSDK_3DS.

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 inicializar o SDK, chame authenticate() e trate o resultado antes de criar a transação.

Informe exatamente uma opção: card, card_hash ou card_id. Com cartão salvo, o setup reutiliza o cartão e realiza uma nova autenticação. O suporte a card_id está disponível desde a 1.1.0.

O contrato do resultado contém card_id e threeds_authentication_id, ambos string. Esta versão não habilita a dispensa AMEX; o caminho anterior da API e seus erros são preservados.

Os dados do cartão devem seguir os formatos de Criar Cartão, inclusive quando enviados em um card_hash. Os dados de customer continuam obrigatórios em todas as formas de entrada.

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. Informe somente uma das formas de entrada aceitas nesta versão.
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 forma de cartão aceita pela versão instalada. Não combine as entradas na mesma chamada.

Atributo	Tipo	Descrição
card_id	string	A partir da 1.1.0. ID de um cartão já salvo na Marlim. Alternativa a card e card_hash, disponível em Sandbox e Produção. Não é aceito no SDK legado.
card_hash	string	Hash de um cartão criptografado manualmente usando uma chave pública.
challenge	boolean	Força o desafio 3DS. Somente em Sandbox. Omita este campo em Produção, inclusive quando seu valor seria false.
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)

Disponível a partir da 1.1.0. 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'
    }
  }
});

Com card ou card_hash, o setup cria um novo identificador de cartão. Use o card_id retornado na transação.

Com card_id como entrada, o setup reutiliza o cartão informado e realiza uma nova autenticação. Reutilizar o cartão não permite reutilizar uma autenticação anterior.

Use o threeds_authentication_id desta tentativa e informe o mesmo valor na transação. O retorno desta versão contém os dois IDs como string.

Response Object

Propriedade	Tipo	Descrição
card_id	string	ID do cartão retornado pelo setup. Utilize este identificador para criar a transação.
threeds_authentication_id	string	ID de autenticação como string. Associa esta tentativa à transação e não comprova aprovação do pagamento.

Exemplo de Response

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

Tipagem TypeScript do resultado

Derive o tipo diretamente da função pública da versão instalada:

import { authenticate } from 'marlim-sdk-3ds';

type ThreeDsResult = Awaited<ReturnType<typeof authenticate>>;

function handleThreeDsResult(result: ThreeDsResult) {
  console.info(result.card_id); // string
  console.info(result.threeds_authentication_id); // string
}

Interfaces próprias precisam refletir o contrato da versão instalada. Carregar o SDK pela CDN não importa as declarações TypeScript; declare o objeto global na aplicação quando necessário.

Criação da transação

No backend do seller, envie os dois IDs retornados, card_id e threeds_authentication_id, para POST /v3/transactions, com os demais campos obrigatórios.

Use o mesmo valor informado em amount; no parcelamento, esse é o valor total da transação. O resultado do SDK não substitui a decisão do antifraude ou da adquirente. O card_id identifica o cartão e sua presença não comprova autenticação 3DS. O threeds_authentication_id associa a autenticação à transação e é específico para cada transação; não reutilize o ID em outra cobrança.

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

Apresentação do desafio

Quando o banco emissor solicita um desafio, o SDK o apresenta em um iframe dentro de um modal sobre o checkout e aguarda sua conclusão. Nesta versão, o modal utiliza estilos na própria página, sem isolamento em Shadow DOM nem ajuste contínuo às mudanças de viewport. Valide a apresentação na WebView e nos tamanhos de tela utilizados pela aplicação.

Aplicativos com WebView

Monte e apresente a WebView antes de chamar authenticate(). Mantenha a WebView visível e montada durante toda a execução, até receber e tratar seu resultado ou erro, com ou sem desafio.

Essa orientação vem de um cenário reproduzido em iPhone físico: com a WebView do aplicativo oculta, a chamada permanecia sem retorno. O iframe interno de coleta de dispositivo deve continuar oculto.

Erros

As mensagens HTTP são extraídas de message, error ou errors, inclusive quando há mensagens válidas em objetos e arrays. Essa leitura ampliada está presente desde a 1.1.0.

Falhas de configuração, validação ou autenticação continuam rejeitando a chamada. O SDK preserva as rejeições existentes: falhas de setup lançam Error; falhas na etapa de autenticação podem rejeitar com uma mensagem em string. Trate ambos no catch.

Um erro técnico ou um ID ausente não representa uma autenticação concluída. Esta versão exige os dois IDs string no resultado; não trate uma falha como dispensa de autenticação.

Histórico de versões

As notas detalham o que mudou em relação à versão anterior e os ajustes necessários no checkout:

• 1.2.0: dispensa AMEX, novo formato de resultado e adaptação dos tipos e do checkout.
• 1.1.1: correções de apresentação do desafio, preservando parâmetros e retorno.
• 1.1.0: entrada card_id e correção da leitura das mensagens de erro.
• 1.0.9 — legado: contrato de autenticação com card ou card_hash e retorno dos IDs string.

Alterações desta versão

Adicionado

• Autenticação com card_id de um cartão já salvo, em Sandbox e Produção, como alternativa a card e card_hash.
• Validação para exigir exatamente uma forma de informar o cartão e rejeitar um card_id vazio.

Corrigido

• Extração de mensagens HTTP nos campos message, error e errors, incluindo respostas em objeto ou array.

Compatibilidade

As entradas card e card_hash continuam disponíveis. O retorno normal preserva card_id e threeds_authentication_id string. Os tipos de rejeição também são preservados: Error no setup e mensagem em string na etapa de autenticação.

Esta versão não reconhece a dispensa AMEX. Atualizar somente a API não habilita esse tratamento em um checkout com SDK anterior à 1.2.0.

Migração

Fixe a dependência ou a URL do SDK em 1.1.0 e valide o checkout em Sandbox. Para cartão salvo, informe card_id e mantenha os dados de customer; cada tentativa continua exigindo nova autenticação.