Marlim SDK 3DS

SDK oficial da Marlim para integração do protocolo de segurança 3DS, oferecendo autenticação segura para as transações.

Documentação

Para informações detalhadas sobre integração com o 3DS, tipos de pagamentos, processamento de transações e outros recursos da API, consulte nossa documentação oficial.

Instalação

> npm install marlim-sdk-3ds
# ou
> yarn add marlim-sdk-3ds
# ou
> pnpm add marlim-sdk-3ds

Uso

Para realizar a autenticação 3DS, é obrigatório possuir o token de sessão. Consulte a seção 3DS na nossa documentação para obter instruções detalhadas sobre como gerar este token.

Autenticação

O SDK disponibiliza um fluxo de autenticação 3DS em apenas duas etapas: inicialização e autenticação.

Exemplo - Inicialização

import MarlimSDK_3DS from 'marlim-sdk-3ds';

// Etapa 1: Inicializar o SDK
MarlimSDK_3DS.init({
  token: 'sua-sessao-aqui',
  env: 'sandbox' // ou 'production'
});

Exemplo - Autenticação

import MarlimSDK_3DS from 'marlim-sdk-3ds';

try {
  // Etapa 2: Autenticação 3DS
  const result = await MarlimSDK_3DS.authenticate({
    amount: 1000, // Valor em centavos
    card: {
      number: '1111111111111111',
      expiration_date: '0126', // Formato MMAA
      cvv: '123',
      holder_name: 'John Doe'
    },
    customer: {
      name: 'Jose Silva',
      document_number: '9999999999',
      email: '[email protected]',
      phone: {
        number: '999999999',
        area_code: '99',
        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'
      }
    }
  });

  console.log('Autenticação bem-sucedida:', result);
  // Resultado: { card_id: "card_123", threeds_authentication_id: "auth_456" }
} catch (error) {
  console.error('Falha na autenticação:', error);
}

Após o resultado

Após obter o threeds_authentication_id e o card_id, já é possível realizar uma transação com autenticação 3DS. Informe ambos os campos na requisição do endpoint de transação para que o pagamento seja processado com sucesso. Para mais detalhes, acesse a nossa documentação.

Referências

init(params: SetupParams): void

Inicializa o SDK com o token de sessão gerado. Deve ser chamado antes de qualquer tentativa de autenticação.

Parâmetros:

• token: string - Seu token de sessão
• env: 'sandbox' | 'production' - Ambiente a ser usado

Exemplo:

MarlimSDK_3DS.init({
  token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
  env: 'sandbox'
});

authenticate(params: ThreedsAuthenticateParams): Promise<AuthenticationResult>

Executa o fluxo completo de autenticação 3DS.

Estrutura de dados:

type CardHash = string;

type CardData = {
  number: string;
  expiration_date: string;
  cvv: string;
  holder_name: string;
}

type CustomerData = {
  name: string;
  document_number: string;
  email: string;
  phone: {
    number: string;
    area_code: string;
    country_code: string;
  };
  address: {
    country: string;
    state: string;
    city: string;
    neighborhood: string;
    number: string;
    street: string;
    zipcode: string;
    complement?: string;
  };
}

Parâmetros:

Campos Obrigatórios

• amount: number - Valor da transação em centavos (ex: 1000 = R$ 10,00)
• customer: CustomerData - Informações do cliente (CustomerData)

Informações do Cartão (escolha uma)

• card?: CardData - Detalhes do cartão (CardData)
• card_hash?: CardHash - Dados do cartão criptografado (Acesse a documentação e confira o passo a passo para criptografar os dados do cartão.)

Campos Opcionais

• challenge?: boolean - Força o fluxo de desafio 3DS. Disponível apenas em sandbox.
• soft_descriptor_challenge?: string - Nome exibido no desafio 3DS. Máximo de 30 caracteres, aceitando letras, números e espaços. Quando não informado, utiliza o nome padrão do seller.

Exemplo:

await MarlimSDK_3DS.authenticate({
  amount: 1000,
  challenge: true, // Opcional: força o desafio 3DS apenas em sandbox
  soft_descriptor_challenge: 'LOJA EXEMPLO',
  card: {
    number: '1111111111111111',
    expiration_date: '0126',
    cvv: '123',
    holder_name: 'John Doe'
  },
  customer: {
    name: 'Jose Silva',
    document_number: '99999999999',
    email: '[email protected]',
    phone: {
      number: '999999999',
      area_code: '99',
      country_code: '99'
    },
    address: {
      country: 'BR',
      state: 'SP',
      city: 'São Paulo',
      neighborhood: 'Centro',
      number: '123',
      street: 'Rua das Flores',
      zipcode: '01001000',
      complement: 'Apto 123'
    }
  }
})

Retorna:

{
  card_id: string;
  threeds_authentication_id: string;
}

Notas Importantes

1. Apenas Navegador: Este SDK só funciona em ambiente Web Browser (não funciona em servidores)

2. Formato dos Dados do Cartão:

   • Números de cartão devem conter apenas dígitos
   • Datas de expiração devem estar no formato MMAA

3. Formato do Valor: Sempre forneça valores em centavos (ex: 1000 = R$ 10,00)

4. Parâmetro Challenge: Disponível apenas no ambiente sandbox para fins de teste

5. Cartão vs Card Hash: Você deve fornecer OU detalhes do card OU card_hash, mas não ambos

6. Nome no desafio 3DS: soft_descriptor_challenge altera apenas o nome exibido durante o desafio 3DS. Ele não substitui o soft_descriptor enviado no endpoint de transação.