Skip to main content
O SDK de segurança faz a autenticação 3D Secure (3DS) inteira no navegador do comprador com uma única chamada, o método process(). Ele coleta os dados do navegador, abre o desafio do banco emissor em um modal quando necessário e devolve o resultado da autenticação. O seu backend envia esse resultado no campo paymentMethod.threeDS ao criar a cobrança.
Para o negócio: o SDK é a forma de integrar o 3DS com menos código no checkout. O cliente vê a tela do banco só quando o emissor pede uma confirmação. Nos demais casos, a autenticação acontece sem interação.
O pacote foi publicado com o nome anterior da marca: @fastpaybr/security-sdk. A classe exportada é Client, que também é o export padrão. Pelo CDN, ela fica em FastPay.Client. Também mantêm o nome anterior a classe de erro FastPayError e o prefixo [FastPay] nas mensagens de log de depuração. Esses nomes são esperados e só mudam com uma nova versão do SDK.

Quando usar

Como funciona

O desenho abaixo mostra o que acontece entre o clique em pagar e a resposta da cobrança quando você usa o SDK. O SDK roda no navegador com a chave pública. O CVV e as parcelas não passam pelo process(): eles vão só na criação da cobrança, feita pelo seu backend com a chave secreta.
1

Inicialize o SDK com a chave pública

Crie o Client com a chave pública (pk_) e chame initialize(). Confira isThreeDSAvailable().
2

Chame process() com os dados da compra

Valor, moeda, cartão e cliente. O endereço é opcional.
3

O SDK coleta os dados do navegador

O SDK coleta sozinho os dados do navegador, inclusive o IP público do comprador, e, quando o emissor pede, faz o fingerprinting (verificação do dispositivo).
4

Desafio, quando necessário

Se o emissor pede confirmação, o SDK abre um modal com a tela do banco. Se não pede, o fluxo segue sem fricção.
5

Resultado

process() devolve o resultado com state. Se for success, envie o resultado ao seu backend. Se o comprador fechar o modal, o resultado é { type: 'none', state: 'failure' }.
6

Seu backend cria a cobrança

POST /v1/charges com o resultado em paymentMethod.threeDS, usando a chave secreta.

Regras de negócio

Instalação

Inicialização

Configuração básica

Verificação de status

Fluxo de autenticação

Processo completo (recomendado)

O método process() conduz todo o fluxo de autenticação:

Estrutura do resultado

Os campos opcionais ficam ausentes quando não há valor; eles não vêm com null. Repasse o objeto ao backend como veio.
Se o comprador fechar o modal do desafio, process() não lança erro. Ele devolve { type: 'none', state: 'failure' }. Trate esse resultado como autenticação não concluída e ofereça nova tentativa.

Estados de autenticação

Customização do modal

Container personalizado

Você pode indicar o seu próprio elemento para receber o iframe do desafio:

Desabilitar o modal automático

Com modal: false, informe challengeContainer. Sem o container, o SDK não tem onde mostrar o desafio e devolve o erro “container is required”.

Customizar a aparência do modal

Exemplos de implementação

Para o desenvolvedor: nos exemplos, createCharge representa uma chamada ao seu backend. É o backend que chama POST /v1/charges com a chave secreta.

Métodos disponíveis

Parâmetros de process()

customer é obrigatório na tipagem e address é opcional. Nenhum dos dois vai para a API: o SDK envia só amount, currency, card e os dados do navegador, que ele coleta sozinho, inclusive o IP público do comprador. process() não recebe installments; as parcelas vão só na criação da cobrança. O tempo limite das requisições que o cliente do SDK faz à API aceita no máximo 30000 ms.

Integração com a API de cobranças

Depois de obter o resultado do 3DS, envie-o ao seu backend, que cria a cobrança com o resultado em paymentMethod.threeDS:
Os campos do cartão na cobrança seguem o contrato de POST /v1/charges: number, holderName, expirationMonth, expirationYear, cvv, installments e threeDS. O items[].unit_price usa a mesma unidade do amount: valor decimal em reais. Para amount: 100.00, use unit_price: 100.00. Os nomes cardNumber e cardholderName não existem no contrato.

Cenários de validação

As validações abaixo só valem quando o 3DS é obrigatório para a sua conta. Nos outros casos, os dados 3DS são repassados sem validação.

Exemplos de erros

Os textos de reason aparecem aqui exatamente como a API devolve, sem ponto final. Trate a recusa pelo prefixo (3ds_required, 3ds_failed, 3ds_incomplete).

Tratamento de erros

Erros lançados pelo SDK

Os erros lançados pelo SDK são instâncias de FastPayError, nome que vem da marca anterior. Com debug: true, as mensagens de log no console começam com [FastPay].

Estados de erro no resultado

Boas práticas

Evite a chave fixa no código:
Prefira a variável de ambiente do build:
A chave pública pode ir para o navegador; a variável de ambiente facilita trocar entre a chave de teste e a de produção.
Os valores padrão são 60 segundos para o fingerprinting e 10 minutos para o desafio:
  • Fingerprinting: 60 segundos de espera pela verificação do dispositivo.
  • Desafio: 10 minutos para o comprador concluir a confirmação no banco. Um valor menor encerra antes a espera no checkout.
  • Se os tempos limite se repetem, investigue a causa antes de mudar o valor.

Erros comuns

Solução de problemas

O padrão é 60 segundos. Tempos limite frequentes indicam problemas de rede, de bloqueio de scripts ou no provedor de 3DS, que precisam ser investigados. Ative debug: true em desenvolvimento e procure no console as mensagens com o prefixo [FastPay].
Opção 1: use o modal automático (padrão).
Opção 2: informe o container se o modal estiver desabilitado.

Perguntas frequentes

A chave pública (pk_). Ela foi feita para o navegador. A chave secreta fica só no backend, que cria a cobrança.
Não. O process() recebe número, nome, mês e ano do cartão. O CVV vai só na criação da cobrança, feita pelo seu backend.
Não. O SDK só autentica. A cobrança é criada pelo seu backend com POST /v1/charges, levando o resultado em paymentMethod.threeDS.
process() não lança erro. Ele devolve { type: 'none', state: 'failure' }. Não crie a cobrança com esse resultado; ofereça nova tentativa.
O SDK foi publicado com o nome anterior da marca. O pacote @fastpaybr/security-sdk, o global FastPay do CDN, a classe de erro FastPayError e o prefixo [FastPay] nos logs continuam assim até uma nova versão do SDK.
A decisão é da sua política de risco. Se a sua conta exige 3DS, só success permite seguir com a cobrança.

Como testar

O 3D Secure é homologado em um cenário específico da sua conta, conforme o roteiro de homologação. No teste, inclua: autenticação com state success seguida de cobrança paid, cobrança sem threeDS (recusa com 3ds_required) e o tratamento de cada state diferente de success no seu checkout.

Veja também

3D Secure: visão geral

Comparativo das três formas de integrar.

3DS via API

As mesmas etapas, chamadas uma a uma.

Criar uma cobrança

Campo paymentMethod.threeDS.

Cartão de crédito

Cobrança com cartão digitado.