As bibliotecas JavaScript auxiliam a integração de pagamentos com cartão na sua aplicação web. Nesta seção, você encontra os guias para criptografar dados do cartão, integrar o antifraude e implementar a autenticação 3DS.
Bibliotecas disponíveis
| Biblioteca | Função na integração | Guia |
|---|---|---|
| Antifraude | Criptografia dos dados do cartão e inicialização dos recursos antifraude. | Biblioteca Antifraude |
| 3DS | Integração da autenticação do titular do cartão, incluindo os fluxos com e sem desafio. | Biblioteca 3DS |
Por onde começar
Escolha o guia conforme o fluxo de pagamento que você vai implementar:
- Pagamento com dados criptografados: consulte a Biblioteca Antifraude, a obtenção da chave pública e o endpoint de criação de pagamento.
- Pagamento com antifraude: consulte os recursos antifraude da Biblioteca Antifraude e os campos do endpoint de pagamento com antifraude.
- Pagamento com 3DS: comece pela Biblioteca 3DS. Depois, consulte a criação de pagamento com 3DS e a validação do desafio.
Como as bibliotecas se conectam à API
Os guias das bibliotecas explicam as etapas executadas na aplicação web, como a criptografia e a coleta de informações do navegador. As páginas dos endpoints explicam quais dados enviar à API e como tratar seus retornos.
Antes de testar a integração, consulte os ambientes disponíveis e a autenticação do Gateway de Pagamentos. Em cada fluxo, siga o guia da biblioteca junto com a documentação do endpoint correspondente.
Exemplo de implementação
A POC demonstra um checkout completo com cartão de crédito e débito, integrando a criptografia dos dados do cartão, o antifraude e a autenticação 3DS no débito.
Baixar POC de checkout com crédito e débito ZIPExemplo educacional para homologação. Use apenas credenciais e cartões de teste.
Como usar a POC e cuidados de integração
O ZIP contém a pasta POC_GATEWAY_FULL_2D_3DS, com a aplicação GatewayCheckout.Api, desenvolvida em ASP.NET Core com Razor Pages e JavaScript.
Configurar e executar
Instale o SDK .NET 10, extraia o ZIP e abra a pasta do projeto em uma IDE, como o Visual Studio Code.
No arquivo GatewayCheckout.Api/appsettings.Development.json, configure Login.UserName e Login.Password com as credenciais de homologação e ajuste ThreeDs.UrlSite3DS para a URL de retorno da sua integração. A BaseUrl desse arquivo já aponta para a API de homologação.
Na pasta extraída POC_GATEWAY_FULL_2D_3DS, execute:
dotnet run --project GatewayCheckout.Api --launch-profile https-devAbra https://localhost:5075 no navegador. O perfil https-dev utiliza o ambiente Development. O projeto também inclui o perfil https-prod, que utiliza appsettings.Production.json e a API de produção, onde os pagamentos são reais.
Fazer um pagamento de teste
- Preencha os dados pessoais e o endereço: clique em Continuar em cada etapa.
- Informe o pagamento: use um cartão de teste, preencha o valor e escolha crédito ou débito. No crédito, selecione as parcelas.
- Revise e pague: confira as informações e clique em Pagar.
- Conclua a autenticação, se solicitada: no débito, siga as instruções do desafio 3DS apresentado pela biblioteca.
- Confira o resultado: aguarde a resposta. Se o resultado não for confirmado, consulte a transação antes de tentar novamente.
Entender o fluxo de integração
Nos dois fluxos, o navegador inicia a sessão antifraude e criptografa o número do cartão com a chave pública obtida pelo backend. O backend autentica a integração e envia o pagamento à API.
- Crédito: envia o pagamento para
POST /v1/payments, sem 3DS, com opção de 1 a 12 parcelas. - Débito: envia o pagamento para
POST /v1/payments/3ds, em uma única parcela, com os dados do navegador para autenticação. Quando há desafio, a biblioteca conduz essa etapa e o backend chamaPOST /v1/payments/3ds/validate-v2antes de apresentar o resultado.
Para acompanhar o código, consulte os guias da Biblioteca Antifraude, da Biblioteca 3DS, da criação de pagamento, da criação de pagamento com 3DS e da validação do desafio.
O integrador é responsável por adaptar o exemplo à sua arquitetura e implementar as validações e o tratamento de erros necessários. Também deve cuidar da observabilidade, da proteção de credenciais, da conformidade e das demais boas práticas de desenvolvimento e segurança. Não compartilhe arquivos com credenciais preenchidas.