A55Pay SDK Reference (V2)

Quick Reference

WhatComplete A55Pay JavaScript SDK V2 reference

WhyIntegrate card payments, hosted checkout, and Apple Pay with the browser-side SDK

Reading Time25 min

DifficultyIntermediate

PrerequisitesAuthentication → Create charge

The A55Pay JavaScript SDK V2 runs in the buyer's browser: it collects card data, runs Device Data Collection (DDC), handles 3DS authentication, processes payments, and surfaces callbacks. Raw card data does not pass through your origin servers.

Prerequisites

Before calling any SDK method, your backend must create a charge without card data. Pass the returned charge_uuid to the frontend.

Create charge →

For Apple Pay, create a charge with type_charge: "applepay". For hosted checkout, use Create checkout and pass the checkout_uuid to A55Pay.open().

Installation

Latest version:

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

Pinned version (recommended for production):

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

After loading, the SDK is available globally as window.A55Pay.

Version pinning

Pin a specific version in production (e.g., a55pay-sdk@4.0.8) for reproducible behavior across deploys.

Properties

`A55Pay.VERSION`

Returns the current SDK version.

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

Methods

`A55Pay.payV2(config)`

Process a credit or debit card payment with automatic device info collection, CyberSource authentication, and 3DS support.

Parameters

Field	Type	Required	Description
`charge_uuid`	`string`	Yes	Charge UUID created via the A55 API
`userData`	`object`	Yes	Payer and card data (see below)
`onSuccess`	`function`	No	Success callback
`onError`	`function`	No	Error callback
`onReady`	`function`	No	Fires when the SDK is ready to process

`userData` fields

Field	Type	Required	Description
`payer_name`	`string`	Yes	Payer full name
`payer_email`	`string`	Yes	Payer email
`payer_tax_id`	`string`	No	Tax ID (CPF/CNPJ in Brazil)
`cell_phone`	`string`	No	Mobile phone number
`holder_name`	`string`	Yes	Name printed on the card
`number`	`string`	Yes	Card number
`expiry_month`	`string`	Yes	Expiry month (e.g., `"12"`)
`expiry_year`	`string`	Yes	Expiry year (e.g., `"2028"`)
`ccv`	`string`	Conditional	Card CVV (required if `card_cryptogram` is absent)
`card_token`	`string`	No	Saved card token
`card_cryptogram`	`string`	Conditional	Card cryptogram (required if `ccv` is absent)
`postal_code`	`string`	Yes	Billing postal code
`street`	`string`	Yes	Billing street
`address_number`	`string`	No	Street number (default: `"n/d"`)
`complement`	`string`	No	Address complement
`neighborhood`	`string`	No	Neighborhood (default: `"n/d"`)
`city`	`string`	Yes	City
`state`	`string`	Yes	State code
`country`	`string`	Yes	Country (ISO alpha-2, e.g., `"BR"`)
`shipping_postal_code`	`string`	No	Shipping postal code (falls back to billing)
`shipping_street`	`string`	No	Shipping street
`shipping_address_number`	`string`	No	Shipping street number
`shipping_complement`	`string`	No	Shipping complement
`shipping_neighborhood`	`string`	No	Shipping neighborhood
`shipping_city`	`string`	No	Shipping city
`shipping_state`	`string`	No	Shipping state
`shipping_country`	`string`	No	Shipping country

Example

<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 ready to process');
      },
      onSuccess: function(result) {
        console.log('Payment approved:', result);
        // result.status = 'confirmed' | 'paid' | 'pending'
        // result.charge_uuid
        // result.data (full charge payload)
        // result.threeds_completed (true if 3DS completed)
      },
      onError: function(error) {
        console.error('Payment error:', error.message);
      }
    });
  });
</script>

Internal flow

`A55Pay.authentication(config)`

Standalone CyberSource Device Data Collection (DDC). Called internally by payV2, but can be invoked separately.

Parameters

Field	Type	Required	Description
`transactionReference`	`string`	Yes	Charge UUID
`cardBrand`	`string`	Yes	Card brand (see values below)
`cardExpiryMonth`	`string`	Yes	Expiry month
`cardExpiryYear`	`string`	Yes	Expiry year
`cardNumber`	`string`	Yes	Card number (no spaces)
`onSuccess`	`function`	No	Success callback
`onError`	`function`	No	Error callback

Valid cardBrand values: Visa, MasterCard, AmericanExpress, Discover, JCB, DinersClub, Hipercard, Elo

Example

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('Authentication failed:', error.message);
  }
});

`A55Pay.getDeviceId()`

Returns the current device ID generated via ThreatMetrix. Generated automatically when the SDK loads.

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

`A55Pay.regenerateDeviceId()`

Forces generation of a new device ID and reloads the ThreatMetrix script.

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

`A55Pay.open(config)`

Opens the A55 checkout (v2) in a modal iframe or embedded container with postMessage communication.

Parameters

Field	Type	Required	Description
`checkoutUuid`	`string`	Yes	Checkout UUID
`display`	`'modal'` \| `'embed'`	No	Display mode (default: `'modal'`)
`containerId`	`string`	No	HTML element ID for embed (auto-created if missing)
`onEvent`	`function`	No	Generic checkout event callback
`onSuccess`	`function`	No	Fires when payment is confirmed
`onClose`	`function`	No	Fires when checkout is closed
`onError`	`function`	No	Error callback

Return value

Returns an object with a close() method to programmatically close the checkout.

var instance = A55Pay.open({
  checkoutUuid: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
  display: 'modal',
  onSuccess: function(data) {
    console.log('Payment confirmed:', data);
    // data.status = 'paid' | 'confirmed'
    // data.chargeUuid
  },
  onError: function(err) {
    console.error('Error:', err.message);
  },
  onClose: function() {
    console.log('Checkout closed');
  },
  onEvent: function(event) {
    console.log('Event received:', event);
  }
});

// Close programmatically:
// instance.close();

Embed example

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

<script>
  A55Pay.open({
    checkoutUuid: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
    display: 'embed',
    containerId: 'my-checkout',
    onSuccess: function(data) {
      console.log('Payment confirmed:', data);
    },
    onClose: function() {
      console.log('Checkout closed');
    }
  });
</script>

`A55Pay.isApplePayAvailable()`

Synchronously checks whether Apple Pay is available in the current browser and device.

if (A55Pay.isApplePayAvailable()) {
  document.getElementById('apple-pay-btn').style.display = 'block';
} else {
  console.log('Apple Pay not available');
}

`A55Pay.startApplePay(config)`

Starts an Apple Pay payment. Must be called inside a click handler (user gesture required).

Activation required

Apple Pay requires prior registration of your merchant in A55's Apple Pay account and hosting a domain verification file. Contact tech.services@a55.tech before integrating.

Parameters

Field	Type	Required	Description
`chargeUuid`	`string`	Yes	Charge UUID created with `type_charge: "applepay"`
`countryCode`	`string`	Yes	ISO 3166-1 alpha-2 country code (e.g., `'BR'`)
`amount`	`string`	Yes	Payment amount (e.g., `'150.00'`)
`currencyCode`	`string`	No	ISO 4217 currency code (default: `'BRL'`)
`merchantDomain`	`string`	No	Merchant domain (default: `'pay.a55.tech'`)
`displayName`	`string`	No	Name shown on the payment sheet (default: `'A55Pay'`)
`supportedNetworks`	`string[]`	No	Supported networks (default: `['visa', 'masterCard', 'elo', 'amex']`)
`onSuccess`	`function`	No	Success callback
`onError`	`function`	No	Error callback
`onClose`	`function`	No	Fires when the user cancels the payment sheet

Example

<button id="apple-pay-btn" style="display:none;">Pay with 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: 'My Store',
      supportedNetworks: ['visa', 'masterCard', 'elo', 'amex'],
      onSuccess: function(result) {
        console.log('Apple Pay approved:', result);
      },
      onError: function(error) {
        console.error('Apple Pay error:', error.message);
      },
      onClose: function() {
        console.log('User cancelled Apple Pay');
      }
    });
  });
</script>

Apple Pay flow

Apple Pay requirements

HTTPS required (does not work over HTTP)
Safari (macOS/iOS) or iOS browsers with WebKit
Card configured in Apple Wallet
Domain verified in Apple Developer Portal

Full Apple Pay documentation →

Complete HTML example

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>A55Pay SDK Example</title>
</head>
<body>
  <h1>Pay with A55Pay</h1>

  <form id="payment-form">
    <input type="text" id="holder" placeholder="Name on card" />
    <input type="text" id="card-number" placeholder="Card number" />
    <input type="text" id="expiry-month" placeholder="MM" />
    <input type="text" id="expiry-year" placeholder="YYYY" />
    <input type="text" id="cvv" placeholder="CVV" />
    <input type="text" id="email" placeholder="Email" />
    <input type="text" id="name" placeholder="Full name" />
    <button type="submit">Pay with Card</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;">
    Pay with Apple Pay
  </button>

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

  <div id="result"></div>

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

    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('Payment approved! Status: ' + result.status);
        },
        onError: function(error) {
          showResult('Error: ' + 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: 'My Store',
        onSuccess: function(result) {
          showResult('Apple Pay approved!');
        },
        onError: function(error) {
          showResult('Apple Pay error: ' + error.message);
        },
        onClose: function() {
          showResult('Apple Pay cancelled');
        }
      });
    });

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

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

Common errors

Error	Cause	Solution
`Missing charge_uuid or userData`	Required parameters missing	Ensure `charge_uuid` and `userData` are provided
`payer_name and payer_email are required`	Payer data missing	Include `payer_name` and `payer_email` in `userData`
`Either ccv or card_cryptogram is required`	No card authentication method	Send `ccv` or `card_cryptogram`
`Apple Pay is not available`	Browser does not support Apple Pay	Use Safari on macOS/iOS with a card in Wallet
`Must create ApplePaySession from user gesture`	`startApplePay` called outside a click handler	Call only inside `addEventListener('click', ...)`
`Invalid countryCode`	Wrong format	Use uppercase ISO 3166-1 alpha-2 (e.g., `"BR"`)
`Invalid amount`	Non-numeric value	Send a numeric string (e.g., `"150.00"`)
`An Apple Pay session is already in progress`	Double click	Disable the button while processing

Security notes

The SDK does not store card data — it is sent directly to the A55 backend
Device ID is generated via ThreatMetrix for fraud detection
3DS 2.0 is handled automatically via CyberSource
Apple Pay tokens are end-to-end encrypted
All communications use HTTPS
Checkout postMessage filters by origin (pay.a55.tech)

Logging

Never log PAN, CVV, or cryptograms from callback payloads. The SDK handles card data in the browser context — keep it there.

Test with sandbox cards

Card Number	Brand	Scenario	Expected Status
`4111 1111 1111 1111`	Visa	Successful payment	confirmed
`5500 0000 0000 0004`	Mastercard	Successful payment	confirmed
`4000 0000 0000 0002`	Visa	Card declined	declined
`4000 0000 0000 0101`	Visa	3DS challenge required	confirmed
`4000 0000 0000 0069`	Visa	Processing error	error

3D Secure →How 3DS authentication works with A55.DataOnly →Highest approval rates via data sharing.Checkout Page →Hosted redirect — zero card data on your site.

Quick Reference

Prerequisites​

Installation​

Properties​

A55Pay.VERSION​

Methods​

A55Pay.payV2(config)​

Parameters​

userData fields​

Example​

Internal flow​

A55Pay.authentication(config)​

Parameters​

Example​

A55Pay.getDeviceId()​

A55Pay.regenerateDeviceId()​

A55Pay.open(config)​

Parameters​

Return value​

Modal example​

Embed example​

A55Pay.isApplePayAvailable()​

A55Pay.startApplePay(config)​

Parameters​

Example​

Apple Pay flow​

Apple Pay requirements​

Complete HTML example​

Common errors​

Security notes​

Test with sandbox cards​

Prerequisites

Installation

Properties

`A55Pay.VERSION`

Methods

`A55Pay.payV2(config)`

Parameters

`userData` fields

Example

Internal flow

`A55Pay.authentication(config)`

Parameters

Example

`A55Pay.getDeviceId()`

`A55Pay.regenerateDeviceId()`

`A55Pay.open(config)`

Parameters

Return value

Modal example

Embed example

`A55Pay.isApplePayAvailable()`

`A55Pay.startApplePay(config)`

Parameters

Example

Apple Pay flow

Apple Pay requirements

Complete HTML example

Common errors

Security notes

Test with sandbox cards