SDK 3DS 1.2.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.2.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, a dispensa explícita de AMEX requer a API compatível e o checkout adaptado para o resultado sem ID de autenticação.

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.

Para AMEX, esta versão pode retornar a dispensa explícita descrita na seção de retorno, com a API compatível.

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.2.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.2.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.2.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.

Os retornos de Visa, Mastercard e Elo preservam os IDs string. Para continuar o pagamento após a dispensa AMEX, são necessários a API compatível e um checkout que aceite o resultado explícito sem ID de autenticação.

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 retorno contém card_id e um threeds_authentication_id string ou, na dispensa AMEX com API compatível, ID nulo e threeds_response. Essa dispensa foi adicionada na 1.2.0.

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.

Quando houver um ID de autenticação, use o ID desta tentativa e informe o mesmo valor na transação. Na dispensa AMEX, o ID de autenticação é nulo e o resultado inclui threeds_response.

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 \| null	ID de autenticação como string; pode ser null somente no resultado explícito de dispensa AMEX. O ID associa a tentativa à transação e não comprova aprovação do pagamento.
threeds_response	object (opcional)	A partir da 1.2.0. Presente e obrigatório no resultado de dispensa AMEX, junto do ID nulo. Ausente no retorno normal com ID de autenticação.
threeds_response.status	string	Obrigatório dentro de threeds_response. Valor atual: skipped, indicando que o 3DS foi dispensado.
threeds_response.reason	string	Obrigatório dentro de threeds_response. Valor atual: amex_not_supported.
threeds_response.message	string	Obrigatório dentro de threeds_response. Mensagem explicando que a autenticação 3DS foi dispensada para AMEX neste fluxo.

Exemplo de Response
{
  "card_id": "card_097v98z0djvnbwaaaai54mxqew",
  "threeds_authentication_id": "32WcjjJ8U445AUaaaafv01"
}

AMEX: pagamento sem 3DS

A partir do SDK 1.2.0, com a API compatível. AMEX retorna o resultado abaixo sem lançar erro. As versões anteriores mantêm o comportamento anterior e não retornam a dispensa.

{
  "card_id": "<id_do_cartao>",
  "threeds_authentication_id": null,
  "threeds_response": {
    "status": "skipped",
    "reason": "amex_not_supported",
    "message": "3DS authentication skipped for AMEX in this flow."
  }
}

Esse resultado não representa uma autenticação aprovada do portador. A Marlim registra a dispensa internamente, sem emitir ID de autenticação 3DS nem abrir coleta de dispositivo ou desafio. Crie a transação com card_id; omita threeds_authentication_id ou envie null. O pagamento continua sujeito às decisões do antifraude e da adquirente.

Atualize o SDK e os checkouts que exigem sempre um ID de autenticação. A continuidade sem ID deve ocorrer somente quando houver threeds_response.status === "skipped" e threeds_response.reason === "amex_not_supported". A ausência de ID, sozinha, não representa dispensa.

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) {
  if (result.threeds_authentication_id === null) {
    console.info(result.threeds_response.status);
    console.info(result.threeds_response.reason);
    console.info(result.threeds_response.message);
    return;
  }

  console.info(result.card_id);
  console.info(result.threeds_authentication_id);
}

Na 1.2.0, habilite strictNullChecks ou strict: true. Conferir o ID nulo identifica o ramo de dispensa, no qual threeds_response é obrigatório.

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 o card_id retornado e o threeds_authentication_id para POST /v3/transactions, com os demais campos obrigatórios. Na dispensa AMEX reconhecida, omita o ID de autenticação ou envie null, conforme descrito no retorno.

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

O modal acompanha as dimensões do desafio e as mudanças da área visível, incluindo teclado e orientação. O isolamento em Shadow DOM reduz a interferência do CSS do checkout, e o ajuste de rolagem mantém a apresentação do desafio. Esses recursos estão presentes desde a 1.1.1.

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 deve ser interpretado como dispensa. A continuidade documentada para AMEX depende do resultado resolvido com ID nulo e threeds_response reconhecido. Uma resposta inconsistente também encerra a chamada com erro.

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

Dispensa explícita da autenticação 3DS para AMEX, sem coleta de dispositivo ou desafio.
Objeto threeds_response com status: "skipped", reason: "amex_not_supported" e uma mensagem explicativa.

Alterado

O tipo de threeds_authentication_id passa a admitir null no resultado de dispensa AMEX.
As declarações TypeScript identificam os dois formatos de resultado: autenticação com ID string e dispensa com ID nulo e threeds_response obrigatório.

Compatibilidade

Visa, Mastercard e Elo mantêm o fluxo e o retorno anteriores. A entrada card_id, adicionada na 1.1.0, continua disponível.

A dispensa depende da API compatível, SDK 1.2.0 e checkout preparado. As versões anteriores mantêm o comportamento AMEX anterior, incluindo os erros existentes. A dispensa não representa autenticação aprovada nem aprovação do pagamento.

Migração

Fixe a dependência ou a URL em 1.2.0.
Preserve o tratamento do ID string e aceite ID nulo somente com o resultado explícito skipped e amex_not_supported.
Atualize interfaces próprias e declarações globais usadas com a CDN, ou derive o tipo de authenticate() no npm.
Valide em Sandbox uma bandeira autenticada e a dispensa AMEX com a API compatível. Use o cartão retornado e o mesmo valor na transação.

SDK​

Versões do SDK​

Instalação​

CDN​

NPM​

Atualizações do SDK​

Compatibilidade entre API, SDK e checkout​

Token de sessão​

Chave pública para criptografia​

Response Object​

Inicialização​

Autenticação​

Propriedades​

Opcionais​

Exemplos de autenticação​

Response Object​

AMEX: pagamento sem 3DS​

Tipagem TypeScript do resultado​

Criação da transação​

Apresentação do desafio​

Aplicativos com WebView​

Erros​

Histórico de versões​

Alterações desta versão​

Adicionado​

Alterado​

Compatibilidade​

Migração​

SDK

Versões do SDK

Instalação

CDN

NPM

Atualizações do SDK

Compatibilidade entre API, SDK e checkout

Token de sessão

Chave pública para criptografia

Response Object

Inicialização

Autenticação

Propriedades

Opcionais

Exemplos de autenticação

Response Object

AMEX: pagamento sem 3DS

Tipagem TypeScript do resultado

Criação da transação

Apresentação do desafio

Aplicativos com WebView

Erros

Histórico de versões

Alterações desta versão

Adicionado

Alterado

Compatibilidade

Migração