A55Pay SDK

Create the charge via API.
On the front‑end, call A55Pay.payV2({ charge_uuid, userData, ...callbacks }). payV2 performs DDC (Device Data Collection), fingerprinting, client IP capture, builds device_info, handles 3DS automatically (modal/iframe), and returns the result via callbacks. The final status is always sent to your webhook_url.

✅ Prerequisites

Serve your page over HTTPS (even locally). Browsers may block DDC/3DS on http://.
The charge must be created beforehand (you will only pass charge_uuid to the SDK).
A publicly reachable webhook_url to receive the final payment status.
(Optional) A parent‑window listener for post‑3DS redirection or UI updates via postMessage.

1) Create the charge (API)

Send the payload below to create a charge and store the returned charge_uuid.

{
  "wallet_uuid": "00000000-0000-0000-0000-000000000000",
  "merchant_id": "11111111-1111-1111-1111-111111111111",
  "payer_name": "John Doe",
  "payer_email": "[email protected]",
  "payer_cell_phone": "+5511999999999",
  "items": [
    {
      "name": "Sample Product",
      "description": "Sample product description",
      "quantity": 1,
      "total_amount": 100.0,
      "unit_amount": 100.0,
      "sku": "SAMPLE-SKU-123",
      "code": "SAMPLE-CODE-456"
    }
  ],
  "currency": "BRL",
  "installment_value": 100.0,
  "installment_count": 1,
  "due_date": "2025-12-31",
  "description": "Sample purchase description",
  "type_charge": "credit_card",
  "webhook_url": "https://webhook.example.com/endpoint",
  "redirect_url": "https://redirect.example.com"
}

Tips

Provide complete payer_*, items[] and address data (when applicable) to improve approval/3DS.

redirect_url is used after 3DS (when challenge occurs).

The final status is delivered via webhook_url.

2) Front‑end — using `A55Pay.payV2`

2.1. Load the SDK

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

2.2. Minimal call

<script>
  A55Pay.payV2({
    charge_uuid: "550e8400-e29b-41d4-a716-446655440000",
    userData: {
      payer_name: "John Doe",
      payer_email: "[email protected]",
      holder_name: "JOHN DOE",
      number: "4111 1111 1111 1111" // PAN or DPAN,
      expiry_month: "02",
      expiry_year: "2032",
      // card_cryptogram: "..." // when using wallets/tokens
      ccv: "123",
      postal_code: "01310-100",
      street: "Av. Paulista",
      address_number: "1000",
      neighborhood: "Bela Vista",
      city: "São Paulo",
      state: "SP",
      country: "BR"
    },
    onReady: () => console.log('Starting DDC + fingerprint + IP capture...'),
    onSuccess: (result) => console.log('Payment OK:', result),
    onError: (err) => console.error('Payment error:', err)
  });
</script>

2.3. Minimal HTML example (English)

Educational sample. Do not log sensitive card data in production.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>A55Pay payV2 — minimal example</title>
</head>
<body>
  <h1>payV2 minimal example</h1>

  <form id="paymentForm">
   <br>

    <label>Payer name <input id="payerName" value="John Doe" required></label><br>
    <label>Payer email <input id="payerEmail" type="email" value="[email protected]" required></label><br>

    <label>Cardholder name <input id="holderName" value="JOHN DOE" required></label><br>
    <label>Card number <input id="cardNumber" value="4111 1111 1111 1111" required></label><br>
    <label>Expiry month <input id="expiryMonth" value="02" required></label><br>
    <label>Expiry year <input id="expiryYear" value="2032" required></label><br>
    <label>CVV <input id="ccv" value="123" required></label><br>

    <label>Postal code <input id="postalCode" value="01310-100" required></label><br>
    <label>Street <input id="street" value="Av. Paulista" required></label><br>
    <label>Number <input id="addressNumber" value="1000" required></label><br>
    <label>Neighborhood <input id="neighborhood" value="Bela Vista" required></label><br>
    <label>City <input id="city" value="São Paulo" required></label><br>
    <label>State <input id="state" value="SP" required></label><br>
    <label>Country <input id="country" value="BR" required></label><br>

    <button id="payButton" type="submit">Pay</button>
  </form>

  <pre id="result"></pre>

  <script src="https://cdn.jsdelivr.net/npm/a55pay-sdk"></script>
  <script>
    const form = document.getElementById('paymentForm');
    const out = document.getElementById('result');
    const btn = document.getElementById('payButton');

    form.addEventListener('submit', function (e) {
      e.preventDefault();
      btn.disabled = true; btn.textContent = 'Processing...';
      out.textContent = 'Starting DDC + fingerprint + IP collection...';

      const userData = {
        payer_name: document.getElementById('payerName').value,
        payer_email: document.getElementById('payerEmail').value,
        holder_name: document.getElementById('holderName').value,
        number: document.getElementById('cardNumber').value,
        expiry_month: document.getElementById('expiryMonth').value,
        expiry_year: document.getElementById('expiryYear').value,
        ccv: document.getElementById('ccv').value,
        postal_code: document.getElementById('postalCode').value,
        street: document.getElementById('street').value,
        address_number: document.getElementById('addressNumber').value,
        neighborhood: document.getElementById('neighborhood').value,
        city: document.getElementById('city').value,
        state: document.getElementById('state').value,
        country: document.getElementById('country').value
      };

      const config = {
        charge_uuid: '550e8400-e29b-41d4-a716-446655440000', // you charge_uuid response
        userData,
        onReady() { out.textContent = 'Collecting device data...'; },
        onSuccess(result) { btn.disabled = false; btn.textContent = 'Pay'; out.textContent = JSON.stringify(result, null, 2); },
        onError(err) { btn.disabled = false; btn.textContent = 'Pay'; out.textContent = 'Error: ' + (err && (err.message || err)); }
      };

      try { A55Pay.payV2(config); } catch (err) {
        btn.disabled = false; btn.textContent = 'Pay';
        out.textContent = 'SDK error: ' + err.message;
      }
    });
  </script>
</body>
</html>

3) What `payV2` does for you

DDC (Device Data Collection) + fingerprinting + IP capture → auto‑populates device_info.
3DS automation: opens a modal/iframe when needed; emits 3ds-auth-complete via postMessage.
Callbacks
- onReady() when data collection/submit starts.
- onSuccess(result) with authorization details.
- onError(error) for validation/network/authorization issues.

4) Optional parent‑window listener (post‑3DS)

Use this when you need to redirect or update UI outside the iFrame/modal.

<script>
  window.addEventListener('message', (event) => {
    if (event.data && event.data.event === '3ds-auth-complete') {
      const chargeUuid = event.data.chargeUuid;
      // Redirect or update your UI
     
    }
  });
</script>

5) `userData` mapping

Field	Required	Example	Notes
`payer_name`	✅	"John Doe"	Payer name.
`payer_email`	✅	"[email protected]"	Payer email.
`holder_name`	✅	"JOHN DOE"	Cardholder name.
`number`	✅	"4111 1111 1111 1111"	PAN or DPAN (`card_cryptogram`).
`expiry_month`	✅	"02"	`MM`.
`expiry_year`	✅	"2032"	`YYYY`.
`ccv`	✅	"123"	Security code.
`card_cryptogram`	—	"..."	For wallets/tokens (when applicable).
`postal_code`	✅	"01310-100"	Postal/ZIP code.
`street`	✅	"Av. Paulista"	Street.
`address_number`	✅	"1000"	Number.
`complement`	—	"Apt 101"	Address complement.
`neighborhood`	✅	"Bela Vista"	Neighborhood.
`city`	✅	"São Paulo"	City.
`state`	✅	"SP"	State/Province.
`country`	✅	"BR"	Country (ISO‑2).
`payer_tax_id`	—	"201.606.848-44"	National ID / tax number.
`cell_phone`	—	"(11) 99999-9999"	Phone number.

6) Best practices

Validate postMessage origins (host allow‑list) before redirecting.
Provide complete userData (including address) to improve approval/3DS.
Never store sensitive card data.

7) Testing & sandbox

Some redirect steps are triggered by the 3DS Server/ACS and might not fully reproduce in sandbox.
For financial validation, create charges under BRL 0.20 and request a refund afterward.
Use HTTPS locally to avoid browser blocks.

8) FAQ

Can I use wallet/token with cryptogram? Yes — pass card_cryptogram in userData (or use the Network Token flow as applicable). Do I need to implement 3DS manually? No. payV2 opens a modal/iframe when needed; you may only listen to the post‑3DS event on the parent window. Where do I get the final result? From your webhook; the SDK callbacks reflect the front‑end state only.