Referência A55Pay SDK (V2)

Quick Reference

WhatReferência completa do A55Pay JavaScript SDK V2

WhyIntegre pagamentos com cartão, checkout hospedado e Apple Pay com o SDK no navegador

Reading Time25 min

DifficultyIntermediate

PrerequisitesAutenticação → Criar cobrança

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

Pré-requisitos

Antes de chamar qualquer método do SDK, seu backend deve criar uma cobrança sem dados de cartão. Passe o charge_uuid retornado para o frontend.

Criar cobrança →

Para Apple Pay, crie uma cobrança com type_charge: "applepay". Para checkout hospedado, use Criar checkout e passe o checkout_uuid para A55Pay.open().

Instalação

Versão mais recente:

<script src="https://cdn.jsdelivr.net/npm/a55pay-sdk@latest/dist/a55pay-sdk.min.js"></script>

Versão fixa (recomendada para produção):

<script src="https://cdn.jsdelivr.net/npm/a55pay-sdk@4.0.8/dist/a55pay-sdk.min.js"></script>

Após carregar, o SDK fica disponível globalmente como window.A55Pay.

Fixar versão

Fixe uma versão específica em produção (ex: a55pay-sdk@4.0.8) para comportamento reproduzível entre deploys.

Propriedades

`A55Pay.VERSION`

Retorna a versão atual do SDK.

console.log(A55Pay.VERSION); // "4.0.8"

Métodos

`A55Pay.payV2(config)`

Pagamento com cartão de crédito/débito com coleta automática de device info, autenticação CyberSource e suporte a 3DS.

Parâmetros

Campo	Tipo	Obrigatório	Descrição
`charge_uuid`	`string`	Sim	UUID da charge criada via API A55
`userData`	`object`	Sim	Dados do pagador e cartão (ver abaixo)
`onSuccess`	`function`	Não	Callback de sucesso
`onError`	`function`	Não	Callback de erro
`onReady`	`function`	Não	Dispara quando o SDK está pronto para processar

Campos de `userData`

Campo	Tipo	Obrigatório	Descrição
`payer_name`	`string`	Sim	Nome completo do pagador
`payer_email`	`string`	Sim	E-mail do pagador
`payer_tax_id`	`string`	Não	CPF/CNPJ do pagador
`cell_phone`	`string`	Não	Telefone celular
`holder_name`	`string`	Sim	Nome impresso no cartão
`number`	`string`	Sim	Número do cartão
`expiry_month`	`string`	Sim	Mês de validade (ex: `"12"`)
`expiry_year`	`string`	Sim	Ano de validade (ex: `"2028"`)
`ccv`	`string`	Condicional	CVV do cartão (obrigatório se não tiver `card_cryptogram`)
`card_token`	`string`	Não	Token de cartão salvo
`card_cryptogram`	`string`	Condicional	Criptograma (obrigatório se não tiver `ccv`)
`postal_code`	`string`	Sim	CEP
`street`	`string`	Sim	Rua
`address_number`	`string`	Não	Número (default: `"n/d"`)
`complement`	`string`	Não	Complemento
`neighborhood`	`string`	Não	Bairro (default: `"n/d"`)
`city`	`string`	Sim	Cidade
`state`	`string`	Sim	Estado (UF)
`country`	`string`	Sim	País (ISO alpha-2, ex: `"BR"`)
`shipping_postal_code`	`string`	Não	CEP de entrega (usa billing se omitido)
`shipping_street`	`string`	Não	Rua de entrega
`shipping_address_number`	`string`	Não	Número de entrega
`shipping_complement`	`string`	Não	Complemento de entrega
`shipping_neighborhood`	`string`	Não	Bairro de entrega
`shipping_city`	`string`	Não	Cidade de entrega
`shipping_state`	`string`	Não	Estado de entrega
`shipping_country`	`string`	Não	País de entrega

Exemplo

<script src="https://cdn.jsdelivr.net/npm/a55pay-sdk@latest/dist/a55pay-sdk.min.js"></script>
<script>
  document.getElementById('pay-btn').addEventListener('click', function() {
    A55Pay.payV2({
      charge_uuid: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
      userData: {
        payer_name: 'Joao da Silva',
        payer_email: 'joao@email.com',
        payer_tax_id: '12345678900',
        cell_phone: '11999998888',
        holder_name: 'JOAO DA SILVA',
        number: '4111 1111 1111 1111',
        expiry_month: '12',
        expiry_year: '2028',
        ccv: '123',
        postal_code: '01310-100',
        street: 'Av Paulista',
        address_number: '1000',
        complement: 'Sala 1',
        neighborhood: 'Bela Vista',
        city: 'Sao Paulo',
        state: 'SP',
        country: 'BR'
      },
      onReady: function() {
        console.log('SDK pronto para processar');
      },
      onSuccess: function(result) {
        console.log('Pagamento aprovado:', result);
        // result.status = 'confirmed' | 'paid' | 'pending'
        // result.charge_uuid
        // result.data (dados completos da charge)
        // result.threeds_completed (true se 3DS foi completado)
      },
      onError: function(error) {
        console.error('Erro no pagamento:', error.message);
      }
    });
  });
</script>

Fluxo interno

`A55Pay.authentication(config)`

Autenticação standalone via CyberSource Device Data Collection (DDC). Usado internamente pelo payV2, mas pode ser chamado separadamente.

Parâmetros

Campo	Tipo	Obrigatório	Descrição
`transactionReference`	`string`	Sim	UUID da charge
`cardBrand`	`string`	Sim	Bandeira do cartão (ver valores)
`cardExpiryMonth`	`string`	Sim	Mês de validade
`cardExpiryYear`	`string`	Sim	Ano de validade
`cardNumber`	`string`	Sim	Número do cartão (sem espaços)
`onSuccess`	`function`	Não	Callback de sucesso
`onError`	`function`	Não	Callback de erro

Valores válidos para cardBrand: Visa, MasterCard, AmericanExpress, Discover, JCB, DinersClub, Hipercard, Elo

Exemplo

A55Pay.authentication({
  transactionReference: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
  cardBrand: 'Visa',
  cardExpiryMonth: '12',
  cardExpiryYear: '2028',
  cardNumber: '4111111111111111',
  onSuccess: function(result) {
    console.log('Session ID:', result.sessionId);
    console.log('Reference ID:', result.referenceId);
    // result.accessToken
    // result.deviceDataCollection
  },
  onError: function(error) {
    console.error('Autenticação falhou:', error.message);
  }
});

`A55Pay.getDeviceId()`

Retorna o device ID atual gerado via ThreatMetrix. Gerado automaticamente ao carregar o SDK.

var deviceId = A55Pay.getDeviceId();
console.log(deviceId); // "a1b2c3d4-e5f6-4g7h-8i9j-k0l1m2n3o4p5"

`A55Pay.regenerateDeviceId()`

Força a geração de um novo device ID e recarrega o script ThreatMetrix.

var newDeviceId = A55Pay.regenerateDeviceId();
console.log('Novo device ID:', newDeviceId);

`A55Pay.open(config)`

Abre o checkout A55 (v2) em iframe modal ou embed com comunicação via postMessage.

Parâmetros

Campo	Tipo	Obrigatório	Descrição
`checkoutUuid`	`string`	Sim	UUID do checkout
`display`	`'modal'` \| `'embed'`	Não	Modo de exibição (default: `'modal'`)
`containerId`	`string`	Não	ID do elemento HTML para embed (criado auto se ausente)
`onEvent`	`function`	Não	Callback para eventos genéricos do checkout
`onSuccess`	`function`	Não	Dispara quando pagamento é confirmado
`onClose`	`function`	Não	Dispara quando checkout é fechado
`onError`	`function`	Não	Callback de erro

Retorno

Retorna um objeto com método close() para fechar o checkout programaticamente.

var instance = A55Pay.open({
  checkoutUuid: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
  display: 'modal',
  onSuccess: function(data) {
    console.log('Pagamento confirmado:', data);
    // data.status = 'paid' | 'confirmed'
    // data.chargeUuid
  },
  onError: function(err) {
    console.error('Erro:', err.message);
  },
  onClose: function() {
    console.log('Checkout fechado');
  },
  onEvent: function(event) {
    console.log('Evento recebido:', event);
  }
});

// Fechar programaticamente:
// instance.close();

Exemplo — Embed

<div id="meu-checkout" style="min-height:600px;"></div>

<script>
  A55Pay.open({
    checkoutUuid: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
    display: 'embed',
    containerId: 'meu-checkout',
    onSuccess: function(data) {
      console.log('Pagamento confirmado:', data);
    },
    onClose: function() {
      console.log('Checkout fechado');
    }
  });
</script>

`A55Pay.isApplePayAvailable()`

Verifica sincronamente se Apple Pay está disponível no browser/dispositivo.

if (A55Pay.isApplePayAvailable()) {
  document.getElementById('apple-pay-btn').style.display = 'block';
} else {
  console.log('Apple Pay não disponível');
}

`A55Pay.startApplePay(config)`

Inicia pagamento via Apple Pay. Deve ser chamado dentro de um handler de clique (user gesture obrigatório).

Ativação necessária

Apple Pay exige cadastro prévio do merchant na conta Apple Pay da A55 e hospedagem do arquivo de verificação de domínio. Contate tech.services@a55.tech antes de integrar.

Parâmetros

Campo	Tipo	Obrigatório	Descrição
`chargeUuid`	`string`	Sim	UUID da charge criada com `type_charge: "applepay"`
`countryCode`	`string`	Sim	Código do país ISO 3166-1 alpha-2 (ex: `'BR'`)
`amount`	`string`	Sim	Valor do pagamento (ex: `'150.00'`)
`currencyCode`	`string`	Não	Código da moeda ISO 4217 (default: `'BRL'`)
`merchantDomain`	`string`	Não	Domínio do merchant (default: `'pay.a55.tech'`)
`displayName`	`string`	Não	Nome exibido no payment sheet (default: `'A55Pay'`)
`supportedNetworks`	`string[]`	Não	Redes suportadas (default: `['visa', 'masterCard', 'elo', 'amex']`)
`onSuccess`	`function`	Não	Callback de sucesso
`onError`	`function`	Não	Callback de erro
`onClose`	`function`	Não	Dispara quando usuário cancela o payment sheet

Exemplo

<button id="apple-pay-btn" style="display:none;">Pagar com Apple Pay</button>

<script src="https://cdn.jsdelivr.net/npm/a55pay-sdk@latest/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: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
      countryCode: 'BR',
      amount: '150.00',
      currencyCode: 'BRL',
      displayName: 'Minha Loja',
      supportedNetworks: ['visa', 'masterCard', 'elo', 'amex'],
      onSuccess: function(result) {
        console.log('Pagamento Apple Pay aprovado:', result);
      },
      onError: function(error) {
        console.error('Erro Apple Pay:', error.message);
      },
      onClose: function() {
        console.log('Usuário cancelou o Apple Pay');
      }
    });
  });
</script>

Fluxo Apple Pay

Requisitos Apple Pay

HTTPS obrigatório (não funciona em HTTP)
Safari (macOS/iOS) ou browsers iOS com WebKit
Cartão configurado na Apple Wallet
Domínio verificado no Apple Developer Portal

Documentação completa Apple Pay →

Exemplo completo (página HTML)

<!DOCTYPE html>
<html lang="pt-BR">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Exemplo A55Pay SDK</title>
</head>
<body>
  <h1>Pagamento com A55Pay</h1>

  <form id="payment-form">
    <input type="text" id="holder" placeholder="Nome no cartão" />
    <input type="text" id="card-number" placeholder="Número do cartão" />
    <input type="text" id="expiry-month" placeholder="MM" />
    <input type="text" id="expiry-year" placeholder="AAAA" />
    <input type="text" id="cvv" placeholder="CVV" />
    <input type="text" id="email" placeholder="Email" />
    <input type="text" id="name" placeholder="Nome completo" />
    <button type="submit">Pagar com Cartão</button>
  </form>

  <button id="apple-pay-btn" style="display:none;background:#000;color:#fff;padding:12px 24px;border:none;border-radius:8px;font-size:16px;cursor:pointer;">
    Pagar com Apple Pay
  </button>

  <button id="open-checkout-btn">Abrir Checkout A55</button>

  <div id="resultado"></div>

  <script src="https://cdn.jsdelivr.net/npm/a55pay-sdk@latest/dist/a55pay-sdk.min.js"></script>
  <script>
    var CHARGE_UUID = 'SEU_CHARGE_UUID_AQUI';
    var resultDiv = document.getElementById('resultado');

    function showResult(msg) {
      resultDiv.textContent = msg;
    }

    document.getElementById('payment-form').addEventListener('submit', function(e) {
      e.preventDefault();

      A55Pay.payV2({
        charge_uuid: CHARGE_UUID,
        userData: {
          payer_name: document.getElementById('name').value,
          payer_email: document.getElementById('email').value,
          holder_name: document.getElementById('holder').value,
          number: document.getElementById('card-number').value,
          expiry_month: document.getElementById('expiry-month').value,
          expiry_year: document.getElementById('expiry-year').value,
          ccv: document.getElementById('cvv').value,
          postal_code: '01310100',
          street: 'Av Paulista',
          city: 'Sao Paulo',
          state: 'SP',
          country: 'BR'
        },
        onSuccess: function(result) {
          showResult('Pagamento aprovado! Status: ' + result.status);
        },
        onError: function(error) {
          showResult('Erro: ' + error.message);
        }
      });
    });

    if (A55Pay.isApplePayAvailable()) {
      document.getElementById('apple-pay-btn').style.display = 'inline-block';
    }

    document.getElementById('apple-pay-btn').addEventListener('click', function() {
      A55Pay.startApplePay({
        chargeUuid: CHARGE_UUID,
        countryCode: 'BR',
        amount: '100.00',
        currencyCode: 'BRL',
        displayName: 'Minha Loja',
        onSuccess: function(result) {
          showResult('Apple Pay aprovado!');
        },
        onError: function(error) {
          showResult('Erro Apple Pay: ' + error.message);
        },
        onClose: function() {
          showResult('Apple Pay cancelado');
        }
      });
    });

    document.getElementById('open-checkout-btn').addEventListener('click', function() {
      A55Pay.open({
        checkoutUuid: CHARGE_UUID,
        display: 'modal',
        onSuccess: function(data) {
          showResult('Checkout confirmado! Status: ' + data.status);
        },
        onError: function(err) {
          showResult('Erro checkout: ' + err.message);
        },
        onClose: function() {
          showResult('Checkout fechado');
        }
      });
    });

    console.log('A55Pay SDK v' + A55Pay.VERSION);
    console.log('Device ID:', A55Pay.getDeviceId());
  </script>
</body>
</html>

Erros comuns

Erro	Causa	Solução
`Missing charge_uuid or userData`	Parâmetros obrigatórios ausentes	Verificar que `charge_uuid` e `userData` estão preenchidos
`payer_name and payer_email are required`	Dados do pagador faltando	Incluir `payer_name` e `payer_email` em `userData`
`Either ccv or card_cryptogram is required`	Sem método de autenticação do cartão	Enviar `ccv` ou `card_cryptogram`
`Apple Pay não está disponível`	Browser sem suporte	Usar Safari em macOS/iOS com cartão na Wallet
`Must create ApplePaySession from user gesture`	`startApplePay` chamado fora de click handler	Chamar apenas dentro de `addEventListener('click', ...)`
`countryCode inválido`	Formato errado	Usar ISO 3166-1 alpha-2 maiúsculo (ex: `"BR"`)
`amount inválido`	Valor não numérico	Enviar string numérica (ex: `"150.00"`)
`Uma sessão Apple Pay já está em andamento`	Duplo clique	Desabilitar botão durante processamento

Notas de segurança

O SDK não armazena dados de cartão — são enviados diretamente ao backend A55
Device ID é gerado via ThreatMetrix para detecção de fraude
3DS 2.0 é tratado automaticamente via CyberSource
Tokens Apple Pay são criptografados de ponta a ponta
Todas as comunicações usam HTTPS
postMessage do checkout filtra por origin (pay.a55.tech)

Logging

Nunca registre PAN, CVV ou criptogramas nos callbacks. O SDK trata dados de cartão no contexto do navegador — mantenha-os lá.

Testar com cartões sandbox

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

3D Secure →Como a autenticação 3DS funciona com a A55.DataOnly →Maiores taxas de aprovação via compartilhamento de dados.Página de Checkout →Redirect hospedado — zero dados de cartão no seu site.

Quick Reference

Pré-requisitos​

Instalação​

Propriedades​

A55Pay.VERSION​

Métodos​

A55Pay.payV2(config)​

Parâmetros​

Campos de userData​

Exemplo​

Fluxo interno​

A55Pay.authentication(config)​

Parâmetros​

Exemplo​

A55Pay.getDeviceId()​

A55Pay.regenerateDeviceId()​

A55Pay.open(config)​

Parâmetros​

Retorno​

Exemplo — Modal​

Exemplo — Embed​

A55Pay.isApplePayAvailable()​

A55Pay.startApplePay(config)​

Parâmetros​

Exemplo​

Fluxo Apple Pay​

Requisitos Apple Pay​

Exemplo completo (página HTML)​

Erros comuns​

Notas de segurança​

Testar com cartões sandbox​

Pré-requisitos

Instalação

Propriedades

`A55Pay.VERSION`

Métodos

`A55Pay.payV2(config)`

Parâmetros

Campos de `userData`

Exemplo

Fluxo interno

`A55Pay.authentication(config)`

Parâmetros

Exemplo

`A55Pay.getDeviceId()`

`A55Pay.regenerateDeviceId()`

`A55Pay.open(config)`

Parâmetros

Retorno

Exemplo — Modal

Exemplo — Embed

`A55Pay.isApplePayAvailable()`

`A55Pay.startApplePay(config)`

Parâmetros

Exemplo

Fluxo Apple Pay

Requisitos Apple Pay

Exemplo completo (página HTML)

Erros comuns

Notas de segurança

Testar com cartões sandbox