Pular para o conteúdo principal

Visão Geral da Integração

Quick Reference

WhatModelos de integração para aceitar pagamentos
WhyEscolha o caminho que combina com seu nível de controle, necessidades de UX e prazo
Reading Time7 min
DifficultyBeginner
PrerequisitesAutenticação → Ambientes

Por que essa decisão importa​

O modelo de integração que você escolhe determina como os dados do cartão trafegam, quem lida com o 3DS e quem cuida da segurança dos dados de cartão. Mudar de modelo depois significa re-arquitetar. Invista 7 minutos aqui para economizar semanas depois.

Escolha erradaConsequência
H2H sem infraestrutura de segurançaVocê manipula dados brutos de cartão sem a estrutura para protegê-los
SDK quando você precisa de controle total no servidorVocê luta contra o SDK em vez de aproveitá-lo
Checkout Page quando você precisa de UX pixel-perfectVocê perde o controle sobre a experiência de pagamento

Matriz comparativa​

CritérioH2H (Host-to-Host)SDK (Embutido)Checkout Page (Redirecionamento)
Tempo de integraçãoSemanasDiasHoras
Segurança dos dadosVocê manipula dados do cartãoO SDK lida com os campos do cartãoTotalmente gerenciado pela A55
Controle de UXTotal — cada pixel é seuAlto — checkout nativo, SDK lida com 3DSLimitado — página hospedada pela A55
Quem manipula dados do cartãoSeus servidoresSDK no navegadorPágina hospedada pela A55
Quem executa o 3DSVocê (trata url_3ds)SDK (frictionless + challenge)A55 (ponta a ponta)
Ideal paraEquipes com controle total do servidorCheckout nativo com menos trabalho de 3DSLançamento mais rápido, sem dados de cartão nos seus servidores

Árvore de decisão​

Regras rápidas
  • Horas para lançar? → Checkout Page
  • UX nativa, sem dados de cartão nos seus servidores? → SDK
  • Controle total do servidor? → H2H

1. H2H (Host-to-Host)​

Seu backend envia dados do cartão, campos do cliente e payloads 3DS diretamente para a A55.

Você lida com: Coleta do cartão, transporte HTTPS, redirecionamento do desafio 3DS, processamento de webhooks.

A A55 lida com: Roteamento ao adquirente, autorização, entrega de webhooks.

VantagemContrapartida
Controle total sobre cada etapa do pagamentoVocê coleta os dados do cartão antes de enviá-los à A55
Lógica personalizada de retentativa e tratamento de errosO fluxo de desafio 3DS exige trabalho no frontend
Acesso direto a todos os parâmetros da APIMaior prazo de integração

2. SDK (Frontend Embutido)​

Incorpore o SDK JavaScript da A55 na sua página de checkout. Ele coleta os dados do cartão, lida com o 3DS e reporta o resultado.

Você lida com: Criação da cobrança no backend, inicialização do SDK no frontend, processamento de webhooks.

O SDK lida com: Renderização dos campos do cartão, device fingerprinting, roteamento 3DS frictionless/challenge, callbacks assíncronos.

VantagemContrapartida
UX de checkout nativa — o SDK renderiza dentro da sua páginaVocê integra e testa o ciclo de vida do SDK
Seguro por padrão — dados do cartão nunca chegam aos seus servidoresMenos flexibilidade que o H2H direto
3DS tratado automaticamente pelo SDKRequer integração com JavaScript no frontend

3. Checkout Page (Redirecionamento)​

Crie uma cobrança com dados mínimos e redirecione o pagador para a página hospedada da A55. A coleta do cartão, o 3DS e a conclusão do pagamento acontecem lá.

Você lida com: Criação da cobrança, redirecionamento, tratamento da URL de retorno, processamento de webhooks.

A A55 lida com: Todo o restante — captura do cartão, 3DS, conclusão do pagamento, UI hospedada.

VantagemContrapartida
Lançamento mais rápido — horas até a produçãoMenos controle sobre a UX de pagamento
Zero dados de cartão nos seus servidores — a A55 cuida dissoRedirecionamento leva o usuário para fora do seu site
Sem necessidade de JavaScript no frontendEstilização da página hospedada é gerenciada pela A55

Resumo de responsabilidades​

ResponsabilidadeH2HSDKCheckout
Criar cobrança no backendVocêVocêVocê
Coletar dados do cartãoVocêSDKA55
Lidar com desafios 3DSVocêSDKA55
Processar webhooksVocêVocêVocê
Segurança dos dados de cartãoVocê gerenciaA55 protege via SDKA55 gerencia tudo
JavaScript no frontendNão necessárioNecessário (SDK)Não necessário

Início rápido da integração​

Independentemente do modelo, a chamada de criação de cobrança no backend é a mesma:

curl -s -X POST https://core-manager.a55.tech/api/v1/bank/wallet/charge/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_uuid": "YOUR_WALLET_UUID",
    "merchant_id": "YOUR_MERCHANT_UUID",
    "payer_name": "Jane Smith",
    "payer_email": "jane@example.com",
    "payer_tax_id": "12345678909",
    "payer_cell_phone": "+5511999999999",
    "installment_value": 250.00,
    "currency": "BRL",
    "due_date": "2026-12-31",
    "description": "Order #42",
    "type_charge": "credit_card",
    "webhook_url": "https://your-app.com/webhooks/a55"
  }'

O que acontece após essa chamada depende do seu modelo de integração:

  • H2H: Inclua o objeto card no payload; trate url_3ds se retornado.
  • SDK: Use o charge_uuid retornado para inicializar o SDK no frontend.
  • Checkout Page: Inclua is_checkout: true; redirecione o pagador para a URL retornada.

Webhooks são a fonte da verdade​

Independentemente do modelo de integração

Trate os webhooks como autoritativos para o estado final do pagamento. Exiba um estado "processando" após o envio até que um webhook confirme o resultado. Estados terminais (paid, error, canceled, refunded) não transitam mais.

ExibirQuando
ProcessandoApós o envio do pagamento
SucessoWebhook confirma paid
FalhaWebhook confirma error ou canceled
Guia H2H →Integração completa servidor-a-servidor com tratamento de 3DS.Guia SDK v2 →Incorpore o SDK da A55 para checkout nativo com 3DS automático.Guia Checkout Page →Redirecione para o checkout hospedado da A55 — integração mais rápida.