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
1
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.
2
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
- Python
- Node.js
- Go
- Java
- PHP
curl -sS -X POST "https://sandbox.api.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://sandbox.api.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://sandbox.api.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://sandbox.api.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://sandbox.api.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://sandbox.api.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;
3
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.
4
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"
}
5
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 |
A55Pay.startApplePay(config) — botão Apple Pay
Use A55Pay.startApplePay() para processar pagamentos Apple Pay nativamente no Safari sem precisar manipular tokens Apple Pay no seu backend.
Ativação necessária
O Apple Pay requer o cadastro prévio do seu merchant na conta Apple Pay da A55 e a hospedagem de um arquivo de verificação de domínio. Entre em contato com tech.services@a55.tech antes de integrar.
Etapa 1 — Criar a cobrança (sem dados de cartão)
Crie a cobrança no seu backend com type_charge: "applepay" mas sem campos de cartão. A cobrança retorna status: "issued" e um charge_uuid.
curl -X POST https://sandbox.api.a55.tech/api/v1/bank/wallet/charge/ \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"merchant_id": "SEU_MERCHANT_UUID",
"wallet_uuid": "SEU_WALLET_UUID",
"payer_name": "John Does",
"description": "Pedido #123",
"due_date": "2025-10-31",
"installment_count": 1,
"installment_value": 100.00,
"currency": "BRL",
"webhook_url": "https://seusite.com/webhook",
"type_charge": "applepay"
}'
{
"charge_uuid": "58e6dabd-71fe-49ed-8f55-ec055648dae7",
"status": "issued",
"type": "applepay",
"charge_payment_url": "https://pay.a55.tech/charge/v2/58e6dabd-71fe-49ed-8f55-ec055648dae7"
}
Etapa 2 — Renderizar o botão Apple Pay
Hospede o arquivo de verificação de domínio em /.well-known/apple-developer-merchantid-domain-association e passe o charge_uuid para A55Pay.startApplePay():
<apple-pay-button
id="apple-pay-btn"
buttonstyle="black"
type="pay"
locale="pt-BR"
style="display:none; --apple-pay-button-width:240px; --apple-pay-button-height:44px; --apple-pay-button-border-radius:8px;"
></apple-pay-button>
<script src="https://cdn.jsdelivr.net/npm/a55pay-sdk/dist/a55pay-sdk.min.js"></script>
<script>
var btn = document.getElementById('apple-pay-btn');
if (A55Pay.isApplePayAvailable()) {
btn.style.display = 'inline-block';
}
btn.addEventListener('click', function () {
A55Pay.startApplePay({
chargeUuid: 'CHARGE_UUID_DA_ETAPA_1',
countryCode: 'BR',
amount: 100.00,
currencyCode: 'BRL', // padrão: 'BRL'
merchantDomain: 'pay.a55.tech', // padrão: 'pay.a55.tech'
displayName: 'Sua Empresa', // padrão: 'A55Pay'
supportedNetworks: ['visa', 'masterCard', 'elo', 'amex'],
onSuccess: function (result) { console.log('Aprovado:', result); },
onError: function (error) { console.error('Erro:', error.message); },
onClose: function () { console.log('Cancelado pelo usuário'); },
});
});
</script>
| Callback | Quando é disparado | O que fazer |
|---|---|---|
onSuccess(result) | Pagamento aprovado | Exibir sucesso, redirecionar para página do pedido |
onError(error) | Recusa ou erro | Exibir mensagem de erro amigável ao usuário |
onClose() | Usuário cancelou a janela Apple Pay | Restaurar UI ao estado inicial |
| Método | payV2 | open | startApplePay |
|---|---|---|---|
| Método de pagamento | Cartão crédito/débito | Cartão crédito/débito | Apple Pay |
| Dados do cartão coletados por | Seu formulário | A55 (hospedado) | Apple Pay (dispositivo) |
| Requer registro Apple | Não | Não | Sim |
| Apenas Safari | Não | Não | Sim |
Documentação completa do Apple Pay →
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.