Integração com SDK (V2)

Quick Reference

WhatA55Pay JS SDK V2

WhyOs dados do cartão ficam no navegador — caminho mais rápido com DDC e 3DS integrados

Reading Time15 min

DifficultyBeginner

PrerequisitesAutenticação → Criar cobrança

O SDK JavaScript A55Pay V2 roda no navegador do comprador: coleta dados do cartão, executa Device Data Collection (DDC), trata a autenticação 3DS, processa o pagamento e dispara callbacks. Dados brutos de cartão não passam pelos servidores de origem do seu site.

Por que usar o SDK

Benefício	Detalhe
Seguro por padrão	Dados do cartão ficam no navegador — a A55 cuida da segurança
Integração mais rápida	Uma tag `script` e uma chamada de função
DDC e 3DS integrados	O SDK executa fingerprinting do dispositivo e autenticação automaticamente
Callbacks de evento	`onSuccess`, `onError`, `onReady` / `onClose` para controle total

Como funciona

Integração passo a passo

Carregar o SDK

Adicione a tag script na página de checkout:

<script src="https://cdn.jsdelivr.net/npm/a55pay-sdk"></script>

Fixação de versão

Fixe uma versão minor em produção (por exemplo, a55pay-sdk@1.2.x) para comportamento reproduzível entre deploys.

Criar uma cobrança no backend

Seu backend cria a cobrança sem dados de cartão — o SDK coletará e enviará os dados do cartão a partir do navegador.

curl -sS -X POST "https://core-manager.a55.tech/api/v1/bank/wallet/charge/" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "wallet_uuid": "00000000-0000-4000-8000-000000000001",
  "merchant_id": "merchant_123",
  "payer_name": "Jane Doe",
  "payer_email": "jane@example.com",
  "payer_tax_id": "12345678901",
  "currency": "BRL",
  "installment_value": 10000,
  "installment_count": 1,
  "type_charge": "credit_card",
  "description": "SDK charge",
  "reference_external_id": "sdk_001",
  "webhook_url": "https://merchant.example/webhooks/a55",
  "redirect_url": "https://merchant.example/return"
}'

import os, requests

r = requests.post(
  "https://core-manager.a55.tech/api/v1/bank/wallet/charge/",
  headers={"Authorization": f"Bearer {os.environ['ACCESS_TOKEN']}",
           "Content-Type": "application/json"},
  json={
      "wallet_uuid": "00000000-0000-4000-8000-000000000001",
      "merchant_id": "merchant_123",
      "payer_name": "Jane Doe", "payer_email": "jane@example.com",
      "payer_tax_id": "12345678901",
      "currency": "BRL", "installment_value": 10000, "installment_count": 1,
      "type_charge": "credit_card",
      "reference_external_id": "sdk_001",
      "webhook_url": "https://merchant.example/webhooks/a55",
  },
)
charge_uuid = r.json()["uuid"]

const res = await fetch(
"https://core-manager.a55.tech/api/v1/bank/wallet/charge/",
{
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ACCESS_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    wallet_uuid: "00000000-0000-4000-8000-000000000001",
    merchant_id: "merchant_123",
    payer_name: "Jane Doe", payer_email: "jane@example.com",
    payer_tax_id: "12345678901",
    currency: "BRL", installment_value: 10000, installment_count: 1,
    type_charge: "credit_card",
    reference_external_id: "sdk_001",
    webhook_url: "https://merchant.example/webhooks/a55",
  }),
}
);
const { uuid: chargeUuid } = await res.json();

payload := map[string]interface{}{
  "wallet_uuid": "00000000-0000-4000-8000-000000000001",
  "type_charge": "credit_card", "currency": "BRL",
  "installment_value": 10000, "installment_count": 1,
  "reference_external_id": "sdk_001",
  "webhook_url": "https://merchant.example/webhooks/a55",
}
body, _ := json.Marshal(payload)
req, _ := http.NewRequest("POST",
  "https://core-manager.a55.tech/api/v1/bank/wallet/charge/", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+os.Getenv("ACCESS_TOKEN"))
req.Header.Set("Content-Type", "application/json")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result struct{ UUID string `json:"uuid"` }
json.NewDecoder(resp.Body).Decode(&result)

String json = """
{"wallet_uuid":"00000000-0000-4000-8000-000000000001",
"type_charge":"credit_card","currency":"BRL",
"installment_value":10000,"installment_count":1,
"reference_external_id":"sdk_001",
"webhook_url":"https://merchant.example/webhooks/a55"}
""";
HttpRequest req = HttpRequest.newBuilder()
  .uri(URI.create("https://core-manager.a55.tech/api/v1/bank/wallet/charge/"))
  .header("Authorization", "Bearer " + System.getenv("ACCESS_TOKEN"))
  .header("Content-Type", "application/json")
  .POST(HttpRequest.BodyPublishers.ofString(json)).build();
HttpResponse<String> resp = HttpClient.newHttpClient()
  .send(req, HttpResponse.BodyHandlers.ofString());
String chargeUuid = new JSONObject(resp.body()).getString("uuid");

$payload = [
  "wallet_uuid" => "00000000-0000-4000-8000-000000000001",
  "type_charge" => "credit_card", "currency" => "BRL",
  "installment_value" => 10000, "installment_count" => 1,
  "reference_external_id" => "sdk_001",
  "webhook_url" => "https://merchant.example/webhooks/a55",
];
$ch = curl_init("https://core-manager.a55.tech/api/v1/bank/wallet/charge/");
curl_setopt_array($ch, [
  CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
      "Authorization: Bearer " . getenv("ACCESS_TOKEN"),
      "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => json_encode($payload),
]);
$chargeUuid = json_decode(curl_exec($ch))->uuid;

Chamar A55Pay.payV2() no navegador

Passe o chargeUuid retornado pelo backend e os dados do cartão coletados no navegador:

A55Pay.payV2({
  charge_uuid: chargeUuid,
  userData: {
    name: 'Jane Doe',
    email: 'jane@example.com',
    document: '12345678901',
    card_number: '4111111111111111',
    card_expiry_month: '12',
    card_expiry_year: '2030',
    card_cvv: '123',
    address: {
      street: 'Av. Paulista 1000',
      city: 'São Paulo',
      state: 'SP',
      zip_code: '01310100',
      country: 'BR',
    },
  },
  onSuccess: (payload) => {
    // Payment confirmed — show success to buyer
    console.log('Charge confirmed:', payload);
  },
  onError: (err) => {
    // Decline or error — show appropriate message
    console.error('Charge failed:', err);
  },
  onReady: () => {
    // SDK initialized — you can show the payment form
  },
});

O SDK fará automaticamente: executar DDC → enviar pagamento → tratar desafio 3DS (se necessário) → chamar onSuccess ou onError.

Tratar os callbacks

Callback	Quando dispara	O que fazer
`onSuccess(payload)`	Pagamento concluído (`confirmed` ou `paid`)	Exibir sucesso, redirecionar para a página do pedido
`onError(err)`	Recusa, erro ou falha de autenticação	Exibir mensagem de erro clara para o usuário
`onReady()`	SDK inicializado e pronto	Opcionalmente exibir o formulário de cartão

Payload esperado em onSuccess:

{
  "chargeUuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "confirmed",
  "reference_external_id": "sdk_001"
}

Payload esperado em onError:

{
  "chargeUuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "error",
  "message": "Card declined by issuer"
}

Confirmar via webhook

Use sempre o webhook como fonte da verdade. O comprador pode fechar o navegador antes de onSuccess disparar.

{
  "charge_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "paid",
  "transaction_reference": "txn_ref_001"
}

`A55Pay.open(config)` — checkout em iframe

Para uma experiência de checkout totalmente hospedada dentro de um iframe ou modal:

const { close } = A55Pay.open({
  checkoutUuid: chargeUuid,
  display: 'modal',        // 'modal' or 'inline'
  containerId: 'checkout',  // required for 'inline'
  onSuccess: (payload) => {
    console.log('Payment confirmed:', payload);
  },
  onError: (err) => {
    console.error('Payment error:', err);
  },
  onClose: () => {
    console.log('Checkout closed by user');
  },
  onEvent: (event) => {
    console.log('Checkout event:', event);
  },
});

Callback	`payV2`	`open`
`onSuccess`	Sim	Sim
`onError`	Sim	Sim
`onReady`	Sim	Não
`onClose`	Não	Sim
`onEvent`	Não	Sim

Testar com cartões de sandbox

Card Number	Brand	Scenario	Expected Status
`4111 1111 1111 1111`	Visa	Pagamento bem-sucedido	confirmed
`5500 0000 0000 0004`	Mastercard	Pagamento bem-sucedido	confirmed
`4000 0000 0000 0002`	Visa	Cartão recusado	declined
`4000 0000 0000 0101`	Visa	Desafio 3DS necessário	confirmed
`4000 0000 0000 0069`	Visa	Erro de processamento	error

Registro de logs

Nunca registre PAN, CVV ou criptogramas vindos dos payloads de callback. O SDK trata os dados do cartão no contexto do navegador — mantenha-os ali.

Quer taxas de aprovação mais altas?

Visa Data Only compartilha dados enriquecidos com emissores pelas trilhas 3DS — sem desafio. Um piloto da Square mostrou ganho de até +646 pontos-base.

Se você usa payV2, o SDK já coleta dados do dispositivo via DDC. Você pode combinar isso com data_only: true na cobrança no backend para maximizar aprovações sem adicionar fricção.

Saiba como ativar Data Only →

3D Secure →authentication() e comportamento do emissor.DataOnly →Maiores taxas de aprovação via compartilhamento de dados.Página de checkout →Redirecionamento hospedado — zero dados de cartão no seu site.SDK V1 (legado) →API antiga — migre para V2.

Quick Reference

Por que usar o SDK​

Como funciona​

Integração passo a passo​