💳 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

✅ 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.

🧪 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

✅ 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

🧪 Testing & Sandbox Tips

💬 FAQ

🧠 Summary

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

🧠 What `payV2` Handles Automatically

🧾 `userData` Reference