Version: v2

Integração com 3DS

O 3DS (3-Domain Secure) é um protocolo de segurança para transações financeiras realizadas no comércio eletrônico com o objetivo de autenticar e fornecer ao usuário uma boa experiência de compra.

Existem dois tipos de autenticação:

Sem desafio (sem atrito): quando o banco emissor entende que as informações fornecidas são suficientes para autenticar o consumidor.

Com desafio (com atrito): quando é necessária uma etapa de validação adicional, uma ação que o consumidor precisa realizar, por exemplo fornecer algum dado enviado via SMS ou a abertura do aplicativo para confirmação da compra. A decisão sobre a aplicação do desafio, o tipo e a tela de desafio no checkout são de responsabilidade do banco emissor do cartão.

Nota

Quando o Banco Emissor entender que o processo de autenticação deverá passar por um desafio, nem a Marlim, a PagSeguro, ou a sua empresa podem ou conseguem modificar a UI das telas e modais que irão aparecer durante esse processo.

O Parceiro da Marlim para o 3DS é a PagSeguro e é uma solução que permite o envio das transações autenticadas para a API de Transações da Marlim e essa integração será direto no checkout da sua empresa, utlizando os processos descritos nessa documentação.

Importante

Antes de fazer a chamada para a API de Transações da Marlim, será necessário fazer a Autenticação com o 3DS, ou seja, todas as transações do seu cliente devem passar por esse processo para ser enviado os parâmetros de retorno dessa autenticação (authentication_status e authentication_id) no body da request da API de Transações.

Fluxo de Autenticação com 3DS

O fluxo de Autenticação com 3DS é composto por 5 etapas:

1º Importar o JavaScript da SDK PagSeguro e Instalar no Front-End do checkout da sua empresa;
2º Chamar o endpoint da API da Marlim para receber uma CHAVE PÚBLICA e montar uma SESSÃO;
3º Montar o Objeto de request da Transação com os dados do cliente e do cartão;
4º Chamar o Método de Autenticação da SDK PagSeguro;
5º Anexar o resultado na API de Transações da Marlim;

1º Importar o SDK PagSeguro

Para importar o SDK PagSeguro, basta adicionar o seguinte código no Front-End do checkout da sua empresa:

<head>
  ... // outros scripts
  <script src="https://assets.pagseguro.com.br/checkout-sdk-js/rc/dist/browser/pagseguro.min.js"></script>
</head>

2º Montar uma Sessão

Antes de chamar o Método de Autenticação (4º etapa), o SDK da PagSeguro precisa ser incializado com o método setUp(), para isso, é necessário chamar o endpoint da API da Marlim para receber uma CHAVE PÚBLICA e depois montar uma SESSÃO.

1º Chamar o endpoint da API da Marlim:

Você irá receber uma CHAVE PÚBLICA dentro do atributo session, ele será usado na etapa seguinte.

Request

curl -X GET -G "https://api.crypto.marlim.co/v2/3ds/session" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \

Response200

{
  "session": "N8bo8UFui7EZyCPZnTcMXxEGDFv........64tfb2BvlNuEGLhJIpeKe+DBQsgA==",
  "expires_at": 1661798079435
}

Atenção!

Utlize essa chamada para API no seu Back-End, evitando expor a sua API KEY da Marlim no Client-Side de sua aplicação.

2º Chamar o método setUp()

Após receber a CHAVE PÚBLICA, você deve iniciar o SDK da PagSeguro passando 2 parâmetros: session e env, seguindo o contexto abaixo:

Atributo	Descrição
session	Uma sessão que indica quem é o merchant dono das interações feitas pela SDK. Essa sessão é válida por 30 minutos e após esse tempo ela precisa ser renovada.
env	O ambiente da SDK que você irá utilizar. Valores aceitos: `PROD` e `SANDBOX`.

PagSeguro.setUp({
  session: 'SUA_SESSAO',
  env: 'ENV'
});

3º Montar o Objeto de Request

Para realizar a autenticação você precisará criar uma request informando os dados da compra, seguindo a tabela abaixo:

Atributo	Tipo	Descrição
customer	object	Objeto que contém os dados do comprador.
customer.name	string	Nome do comprador.
customer.email	string	Email do comprador.
customer.phones[]	array	Lista de telefones do comprador. Pelo menos um dos objetos deve ser do Type: MOBILE.
customer.phones[].country	string	DDI do telefone do comprador.
customer.phones[].area	string	DDD do telefone do comprador.
customer.phones[].number	string	Número do telefone do comprador.
customer.phones[].type	string	Tipo do telefone do comprador. Valores aceitos: `MOBILE`, `HOME` e `BUSINESS`.
paymentMethod	object	Objeto que contém os dados do meio de pagamento.
paymentMethod.type	string	Objeto que contém os dados do meio de pagamento. Valores aceitos: `CREDIT_CARD` e `DEBIT_CARD`.
paymentMethod.installments	number	Em quantas parcelas o pagamento será realizado.
paymentMethod.card	object	Objeto que contém os dados do cartão utilizado na compra.
paymentMethod.card.number	string	Número do cartão utilizado na compra.
paymentMethod.card.expMonth	string	Mês de expiração do cartão utilizado na compra. Deve ser um valor entre 01 e 12.
paymentMethod.card.expYear	string	Ano de expiração do cartão utilizado na compra. Deve ser um valor de 4 digitos.
paymentMethod.card.holder	object	Objeto que contém os dados do titular do cartão utilizado na compra.
paymentMethod.card.holder.name	string	Nome do titular do cartão utilizado na compra.
amount	object	Objeto que contém os dados do valor da compra.
amount.value	number	Valor final a ser cobrado com as taxas (Adquirência / Marlim). Deve ser passado em centavos e o no mínimo de R$ 1,00 (100).
amount.currency	string	Por enquanto o único valor aceito: `BRL`.
billingAddress	object	Objeto que contém os dados do endereço de cobrança do cartão.
billingAddress.postalCode	string	CEP do endereço de cobrança do cartão.
billingAddress.country	string	País do endereço de cobrança do cartão. Por enquanto o único valor aceito: `BRA`.
billingAddress.regionCode	string	Código do Estado do endereço de cobrança do cartão, no formato sigla do estado no padrão ISO 3166-2 Ex: SP, RJ, MG...
billingAddress.city	string	Cidade do endereço de cobrança do cartão.
billingAddress.street	string	Rua do endereço de cobrança do cartão.
billingAddress.number	string	Número do endereço de cobrança do cartão.
billingAddress.complement	string	Parâmetro opcional do complemento do endereço de cobrança do cartão.
dataOnly	boolean	Flag indicando o fluxo 3DS Data-Only, por enquanto o único valor aceito: `false`.
beforeChallenge	function	Função opcional que recebe um parâmetro e é chamado antes de um desafio. Em Desenvolvimento.

4º Chamar Autenticação 3DS

Todos esses valores devem ser adicionados dentro de um atributo data:{}, utlizando a função authenticate3DS() como segue o exemplo abaixo:

PagSeguro.authenticate3DS({
  data: {
    customer: {
      name: 'Jose da Silva',
      email: 'jose@gmail.com',
      phones: [
        {
          country: '55',
          area: '11',
          number: '999999999',
          type: 'MOBILE'
        }
      ]
    },
    paymentMethod: {
      type: 'CREDIT_CARD',
      installments: 1,
      card: {
        number: "4000000000002370",
        expMonth: "02",
        expYear: "2026",
        holder: {
          name: "Joao Silva"
        }
      }
    },
    amount: {
      value: 100000,
      currency: 'BRL'
    },
    billingAddress: {
      street: 'Av. Paulista',
      number: '2073',
      complement: 'Apto 100',
      regionCode: 'SP',
      country: 'BRA',
      city: 'São Paulo',
      postalCode: '01311300'
    },
    dataOnly: false,
  }
}).then(result => {
    // enviar resultado para API de Transações da Marlim
}).catch((err) => {         
  // tratar erros
})

O método authenticate3DS retorna uma Promise. Caso a Promisse conclua com sucesso (seja resolvida), o método then é acionado com objeto contendo os seguintes atributos:

Atributo	Descrição
status	Representa o status final do fluxo de autenticação. Pode ter 3 valores: `AUTH_FLOW_COMPLETED`, `AUTH_NOT_SUPPORTED` e `CHANGE_PAYMENT_METHOD`. Esse valor será anexado ao atributo `authentication_status` da API Marlim de Transações
id	Representa o id da autenticação. Esse valor será anexado ao atributo `authentication_id` da API Marlim de Transações

5º API de Transações Marlim

Após receber o resultado da autenticação 3DS com os valores status e id, deve ser chamada a API de Transações da Marlim, anexando os 2 valores aos atributos correspondentes, seguindo o exemplo abaixo:

Request

curl -X POST "https://api.crypto.marlim.co/v2/transactions" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "...": "...",
  "authentication_status": "AUTH_FLOW_COMPLETED",
  "authentication_id": "3DS-C4669D-0DF8-48DF-BBB3-6E22FBA865AF"
}'

Nota

Importante

Fluxo de Autenticação com 3DS​

1º Importar o SDK PagSeguro​

2º Montar uma Sessão​

1º Chamar o endpoint da API da Marlim:

Atenção!

2º Chamar o método setUp()

3º Montar o Objeto de Request​

4º Chamar Autenticação 3DS​

5º API de Transações Marlim​

Fluxo de Autenticação com 3DS

1º Importar o SDK PagSeguro

2º Montar uma Sessão

3º Montar o Objeto de Request

4º Chamar Autenticação 3DS

5º API de Transações Marlim