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.
@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 peloprocess(): eles vão só na criação da cobrança, feita pelo seu backend com a chave secreta.
Inicialize o SDK com a chave pública
Client com a chave pública (pk_) e chame initialize(). Confira isThreeDSAvailable().Chame process() com os dados da compra
O SDK coleta os dados do navegador
Desafio, quando necessário
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' }.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
- NPM
- CDN
Inicialização
Configuração básica
Verificação de status
Fluxo de autenticação
Processo completo (recomendado)
O métodoprocess() conduz todo o fluxo de autenticação:
Estrutura do resultado
null. Repasse o objeto ao backend como veio.
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
Customizar a aparência do modal
Exemplos de implementação
- React
- JavaScript puro
- Vue.js
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 empaymentMethod.threeDS:
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
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 deFastPayError, 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
1. Sempre inicialize antes de usar
1. Sempre inicialize antes de usar
2. Trate todos os estados
2. Trate todos os estados
3. Use variáveis de ambiente para a chave
3. Use variáveis de ambiente para a chave
4. Mostre o carregamento ao cliente
4. Mostre o carregamento ao cliente
5. Ative o log de depuração só em desenvolvimento
5. Ative o log de depuração só em desenvolvimento
6. Ajuste os tempos limite só se necessário
6. Ajuste os tempos limite só se necessário
- 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
Modal não aparece
Modal não aparece
Tempo limite no fingerprinting
Tempo limite no fingerprinting
debug: true em desenvolvimento e procure no console as mensagens com o prefixo [FastPay].Erro 3DS provider not available
Erro 3DS provider not available
Erro container is required
Erro container is required
Dados do cartão inválidos
Dados do cartão inválidos
Perguntas frequentes
Qual chave uso no SDK?
Qual chave uso no SDK?
pk_). Ela foi feita para o navegador. A chave secreta fica só no backend, que cria a cobrança.Preciso enviar o CVV ao SDK?
Preciso enviar o CVV ao SDK?
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.O SDK cria a cobrança?
O SDK cria a cobrança?
POST /v1/charges, levando o resultado em paymentMethod.threeDS.O que acontece se o comprador fechar o modal?
O que acontece se o comprador fechar o modal?
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.Por que o pacote e a classe de erro usam o nome anterior da marca?
Por que o pacote e a classe de erro usam o nome anterior da marca?
@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.O que fazer quando o estado é unenrolled ou disabled?
O que fazer quando o estado é unenrolled ou disabled?
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 comstate 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
3DS via API
Criar uma cobrança
paymentMethod.threeDS.
