💳 A55Pay SDK — Payment Integration Guide

End-to-end guide for integrating A55Pay SDK to process card payments with 3DS authentication, device fingerprinting, and automated callbacks.
Secure, fast, and developer-friendly.

🧭 Payment Flow Overview

sequenceDiagram
    autonumber
    participant Merchant as "🛒 Merchant"
    participant A55 as "💳 API A55"
    participant Script as "📜 A55 SDK"
    participant Serve3DS as "🛡️ A55 Server"

    rect rgba(191,223,255,0.2)
        Merchant->>A55: Create payment
        activate A55
        Note right of A55: Payment transaction starts
        A55-->>Merchant: Returns charge_uuid (for SDK)
        deactivate A55
    end

    Merchant->>Script: Initializes SDK using charge_uuid
    Script->>Serve3DS: Performs DDC, fingerprint, 3DS, payment data
    activate Serve3DS

    alt Challenge required
        Serve3DS-->>Script: 3DS challenge required
        Script->>Merchant: Displays 3DS modal to customer
        Merchant-->>Script: Customer completes challenge
    else No challenge required
        Serve3DS-->>Script: Returns result
    end
    deactivate Serve3DS

    rect rgba(200,255,200,0.2)
        Script->>A55: Sends authentication & payment data
        activate A55
        A55-->>Merchant: Returns final status (success/failure)
        deactivate A55
    end

🔍
Click here to view full diagram with zoom

✅ Prerequisites

Before integrating:

Serve your checkout over HTTPS (required for DDC/3DS).
The charge must already exist — created via API.
Provide a public webhook_url to receive final status updates.
(Optional) Implement a parent window listener for post-3DS updates or redirections.

⚙️ Step 1: Create a Charge (API)

Create the charge and store the returned charge_uuid to be used by the SDK.

{
  "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",
  "threeds_authentication": true,
  "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

Include full payer_*, items[], and address data for better 3DS results.

redirect_url is used after the 3DS challenge (if needed).

Final transaction status is always delivered to your webhook_url.

🧩 Step 2: Front-end Integration — `A55Pay.payV2`

2.1 Load the SDK

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

2.2 Minimal HTML Example

⚠️
For testing only — never log sensitive data in production.

<!DOCTYPE html>
<html>
<head>
  <title>A55Pay SDK Example</title>
</head>
<body>
  <script src="https://cdn.jsdelivr.net/npm/a55pay-sdk"></script>
  <script>
    const userData = {
      // Payer
      payer_name: "Full Name",
      payer_email: "[email protected]",
      payer_tax_id: "00000000000",
      cell_phone: "5511999999999",
      
      // Card
      holder_name: "NAME ON CARD",
      number: "0000000000000000",
      expiry_month: "MM",
      expiry_year: "YYYY",
      ccv: "123", // or card_cryptogram

      // Alternative card options
      card_token: "card_token",
      card_cryptogram: "3ds_cryptogram",
      
      // Billing address
      postal_code: "00000000",
      street: "Street Name",
      address_number: "123",
      neighborhood: "Neighborhood Name",
      complement: "Apt 101",
      city: "City Name",
      state: "SP", // 2 caracteres
      country: "BR", // 2 caracteres

      // Shipping address (if different from billing)
      shipping_postal_code: "00000000",
      shipping_street: "Shipping Street",
      shipping_address_number: "456",
      shipping_complement: "Block B",
      shipping_neighborhood: "Shipping Neighborhood",
      shipping_city: "Shipping City",
      shipping_state: "RJ", // 2 caracteres
      shipping_country: "BR" // 2 caracteres
    };

    const config = {
      charge_uuid: "550e8400-e29b-41d4-a716-446655440000",
      userData,
      onReady: () => console.log("SDK ready – starting authentication"),
      onSuccess: (result) => console.log("✅ Payment success:", result),
      onError: (error) => console.log("❌ Payment error:", error)
    };

    A55Pay.payV2(config);
  </script>
</body>
</html>

🧠 What `payV2` Handles Automatically

DDC (Device Data Collection) + fingerprint + IP capture → builds device_info.
3DS Automation → opens modal/iframe when required.
Post-3DS event → emits 3ds-auth-complete via postMessage.

Callbacks

Callback	Trigger	Description
`onReady()`	When SDK initializes	Starts authentication and data collection
`onSuccess(result)`	Payment success	Returns full authorization response
`onError(error)`	Any issue	Validation, network, or 3DS errors

🪄 Optional: Parent-Window Listener

Handle post-3DS events or UI updates from inside your checkout page.

<script>
  window.addEventListener('message', function (event) {
    if (event.data && event.data.event === '3ds-auth-complete') {
      const chargeUuid = event.data.chargeUuid;
      // custom actions
    }
    // if send redirect_url
		if (event.data && event.data.event === '3ds-redirect-request') {
       window.location.replace(event.data.redirectUrl);
    }
  });
</script>

🧾 `userData` Reference

Field	Required	Example	Description
`payer_name`	✅	John Doe	Full name of the payer
`payer_email`	✅	[email protected]	Payer email address
`payer_tax_id`	—	00000000000	National ID or tax number
`cell_phone`	—	5511999999999	Payer phone number
`holder_name`	✅	JOHN DOE	Cardholder name
`number`	✅	4111111111111111	PAN or DPAN
`expiry_month`	✅	12	Month (MM)
`expiry_year`	✅	2032	Year (YYYY)
`ccv`	✅	123	Security code
`card_token`	—	86f22388-bb59-4c47-ae00-3c79803e364f	Tokenized card reference
`card_cryptogram`	—	QmFzZTY0Rm9yQ2lwdG9ncmFtMTIz==	Used in 3DS or tokenized flows
`postal_code`	✅	01310100	ZIP/postal code
`street`	✅	Av. Paulista	Street name
`address_number`	✅	1000	Address number
`neighborhood`	✅	Bela Vista	Neighborhood
`complement`	—	Apt 101	Optional complement
`city`	✅	São Paulo	City name
`state`	✅	SP	State/province
`country`	✅	BR	ISO-2 country code
`shipping_postal_code`	—	04038001	Shipping ZIP (if different)
`shipping_street`	—	Rua Fidêncio Ramos	Shipping street
`shipping_address_number`	—	308	Shipping number
`shipping_complement`	—	Tower A	Shipping complement
`shipping_neighborhood`	—	Vila Olímpia	Shipping neighborhood
`shipping_city`	—	São Paulo	Shipping city
`shipping_state`	—	SP	Shipping state
`shipping_country`	—	BR	Shipping country

🔄 Full Execution Flow

Initialization: SDK loads and generates Device ID (fingerprint).
Authentication: Device Data Collection .
IP Collection: Multiple methods.
Transmission: Sends payload to A55 API.
3DS: Opens modal for authentication if required.
Result: Returns via callback and webhook.

🎯 SDK Integration - Render Checkout via iframe

Instead of redirecting your users to the checkout page, you can embed the checkout directly in your website using the A55Pay SDK. This provides a seamless payment experience with two display modes: modal (overlay) or embed (inline).

📦 Installation

Include the SDK in your HTML:

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

🔧 Basic Usage

Use the payment_link_uuid (also called checkoutUuid) returned from the API to open the checkout:

A55Pay.open({
  checkoutUuid: '0b9bffcb-2d96-42bb-8641-279bfc8aac19',
  display: 'modal', // 'modal' or 'embed'
  containerId: 'checkout-container', // Only required for 'embed' mode
  
  // Callbacks
  onSuccess: (data) => {
    console.log('Payment successful!', data);
    // data contains: { chargeUuid, status, timestamp, data: [...] }
  },
  
  onError: (error) => {
    console.error('Payment error:', error);
  },
  
  onEvent: (event) => {
    console.log('Checkout event:', event);
  },
  
  onClose: () => {
    console.log('Checkout closed');
  }
});

📋 Configuration Options

Parameter	Type	Required	Description
`checkoutUuid`	`string`	✅ Yes	The `payment_link_uuid` returned from the API
`display`	`'modal' \| 'embed'`	❌ No	Display mode. Default: `'modal'`
`containerId`	`string`	⚠️ Conditional	Required for `'embed'` mode. The ID of the container element. If not provided, a container will be created automatically
`onSuccess`	`function`	❌ No	Called when payment is successful (status: `paid`, `confirmed`, or `ok`)
`onError`	`function`	❌ No	Called when payment fails (status: `error`)
`onEvent`	`function`	❌ No	Called for other events during the checkout process
`onClose`	`function`	❌ No	Called when the checkout is closed (always triggered)

🎨 Display Modes

1️⃣ Modal Mode (Default)

Opens the checkout in a centered modal overlay with a modern design, backdrop blur, and close button:

<!DOCTYPE html>
<html>
<head>
  <title>Checkout Modal</title>
</head>
<body>
  <button onclick="openCheckout()">Pay Now</button>
  
  <script src="https://cdn.jsdelivr.net/npm/a55pay-sdk"></script>
  <script>
    function openCheckout() {
      A55Pay.open({
        checkoutUuid: '0b9bffcb-2d96-42bb-8641-279bfc8aac19',
        display: 'modal',
        
        onSuccess: (data) => {
          alert('Payment successful!');
          console.log('Payment data:', data);
        },
        
        onError: (error) => {
          alert('Payment failed: ' + error.message);
        },
        
        onClose: () => {
          console.log('User closed the checkout');
        }
      });
    }
  </script>
</body>
</html>

2️⃣ Embed Mode

Embeds the checkout inline within a specific container on your page:

<!DOCTYPE html>
<html>
<head>
  <title>Checkout Embed</title>
  <style>
    #checkout-container {
      width: 100%;
      min-height: 600px;
      border: 1px solid #e0e0e0;
      border-radius: 8px;
    }
  </style>
</head>
<body>
  <h1>Complete Your Payment</h1>
  
  <!-- The checkout will be rendered inside this container -->
  <div id="checkout-container"></div>
  
  <script src="https://cdn.jsdelivr.net/npm/a55pay-sdk"></script>
  <script>
    A55Pay.open({
      checkoutUuid: '0b9bffcb-2d96-42bb-8641-279bfc8aac19',
      display: 'embed',
      containerId: 'checkout-container',
      
      onSuccess: (data) => {
        console.log('Payment completed:', data);
        // Redirect to success page or show confirmation
        window.location.href = '/payment-success';
      },
      
      onError: (error) => {
        console.error('Payment error:', error);
        // Show error message to user
      }
    });
  </script>
</body>
</html>

📨 Callback Payloads

onSuccess Payload

Triggered when payment is successful (status: paid, confirmed, or ok):

{
  chargeUuid: "abc-123",
  status: "paid", // or "confirmed" or "ok"
  timestamp: "2024-01-15T10:30:00.000Z",
  data: [{
    charge_uuid: "abc-123",
    type_charge: "pix",
    value: 100.00,
    currency: "BRL",
    status: "paid"
  }]
}

onError Payload

Triggered when payment fails (status: error):

{
  status: "error",
  message: "Payment declined by issuer",
  chargeUuid: "abc-123",
  timestamp: "2024-01-15T10:30:00.000Z"
}

onEvent Payload

Triggered for other checkout events:

{
  event: "payment-method-selected",
  method: "pix",
  timestamp: "2024-01-15T10:29:30.000Z"
}

🧪 Testing & Sandbox Tips

Some 3DS redirects may not fully reproduce in sandbox.
Use charges below BRL 0.20 for testing and refund afterward.
Always serve pages over HTTPS, even locally.

💬 FAQ

Can I use a token or cryptogram instead of raw PAN?
Yes. Include either card_token or card_cryptogram in userData.

Do I need to build the 3DS UI manually?
No. The SDK automatically opens a modal/iframe for the 3DS challenge.

Where do I receive the final payment status?
Your backend webhook receives the final, authoritative status from A55.

🧠 Summary

The A55Pay SDK abstracts complex payment flows — device fingerprinting, 3DS, and callbacks — into a simple front-end integration.
Developers can securely accept card payments with minimal effort and high approval rates.

💳 A55Pay SDK — Payment Integration Guide

🧭 Payment Flow Overview

Click here to view full diagram with zoom

✅ Prerequisites

⚙️ Step 1: Create a Charge (API)

🧩 Step 2: Front-end Integration — A55Pay.payV2

2.1 Load the SDK

2.2 Minimal HTML Example

For testing only — never log sensitive data in production.

🧠 What payV2 Handles Automatically

Callbacks

🪄 Optional: Parent-Window Listener

🧾 userData Reference

🔄 Full Execution Flow

🎯 SDK Integration - Render Checkout via iframe

📦 Installation

🔧 Basic Usage

📋 Configuration Options

🎨 Display Modes

1️⃣ Modal Mode (Default)

2️⃣ Embed Mode

📨 Callback Payloads

onSuccess Payload

onError Payload

onEvent Payload

🧪 Testing & Sandbox Tips

💬 FAQ

🧠 Summary

🧩 Step 2: Front-end Integration — `A55Pay.payV2`

🧠 What `payV2` Handles Automatically

🧾 `userData` Reference