a55pay-sdk

v1.0.20

Published

25 days ago

Embeddable Payment SDK for 3DS integration (A55)

0High
0Medium
0Low

access55

A55Pay SDK - Documentation

JavaScript SDK for payment integration with 3DS authentication, Device Data Collection and ThreatMetrix fingerprinting.

📦 Installation

Include the SDK in your HTML:

<script src="path/to/a55pay-sdk.js"></script>

🚀 Basic Usage

PayV2 - Complete Payment with Authentication

<!DOCTYPE html>
<html>
<head>
    <title>A55Pay SDK - Example</title>
</head>
<body>
    <script src="a55pay-sdk.js"></script>
    <script>
        // Mock data for testing
        const userData = {
            // Required payer data
            payer_name: "Maria Silva Santos",
            payer_email: "[email protected]",
            
            // Optional payer data
            payer_tax_id: "123.456.789-01",
            cell_phone: "(11) 98765-4321",
            
            // Card data
            holder_name: "MARIA S SANTOS",
            number: "4111111111111111",
            expiry_month: "12",
            expiry_year: "2028",
            ccv: "123",
            // card_cryptogram: "optional",
            
            // Billing address
            postal_code: "01310-100",
            street: "Av. Paulista",
            address_number: "1578",
            complement: "Suite 1001",
            neighborhood: "Bela Vista",
            city: "São Paulo",
            state: "SP",
            country: "BR",
            
            // Shipping address (optional - if not provided, uses billing address)
            shipping_postal_code: "04038-001",
            shipping_street: "Rua Fidêncio Ramos",
            shipping_address_number: "308",
            shipping_complement: "Tower A - Apt 502",
            shipping_neighborhood: "Vila Olímpia",
            shipping_city: "São Paulo",
            shipping_state: "SP",
            shipping_country: "BR"
        };

        // Payment configuration
        const config = {
            charge_uuid: "550e8400-e29b-41d4-a716-446655440000",
            userData: userData,
            
            onReady: function() {
                console.log("SDK ready - starting authentication and data collection");
            },
            
            onSuccess: function(result) {
                console.log("Payment completed successfully:", result);
            },
            
            onError: function(error) {
                console.log("Payment error:", error);
            }
        };

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

🛠️ Available Methods

1. A55Pay.payV2(config)

Main method for payments with complete authentication.

Parameters:

charge_uuid (string, required): Transaction UUID
userData (object, required): User and card data
onReady (function, optional): Callback when SDK is ready
onSuccess (function, optional): Success callback
onError (function, optional): Error callback

2. A55Pay.authentication(config)

Tests authentication only without making payment.

A55Pay.authentication({
    transactionReference: "550e8400-e29b-41d4-a716-446655440000",
    cardBrand: "Visa",
    cardExpiryMonth: "12",
    cardExpiryYear: "2028",
    cardNumber: "4111111111111111",
    
    onSuccess: function(result) {
        console.log("Authentication completed:", result);
        // result.sessionId can be used in payment
    },
    
    onError: function(error) {
        console.log("Authentication error:", error);
    }
});

3. A55Pay.getDeviceId()

Returns the current Device ID generated by ThreatMetrix.

const deviceId = A55Pay.getDeviceId();
console.log("Device ID:", deviceId);

4. A55Pay.regenerateDeviceId()

Generates a new Device ID.

const newDeviceId = A55Pay.regenerateDeviceId();
console.log("New Device ID:", newDeviceId);

📋 userData Structure

Required Fields

const userData = {
    // Payer
    payer_name: "Full Name",
    payer_email: "[email protected]",
    payer_tax_id: "000.000.000-00",
    cell_phone: "(11) 99999-9999",
    
    // Card
    holder_name: "NAME ON CARD",
    number: "0000000000000000",
    expiry_month: "MM",
    expiry_year: "YYYY",
    ccv: "123", // OR card_cryptogram

    // Alternative card
    card_token: "card_token",
    card_cryptogram: "3ds_cryptogram",
    
    // Address
    postal_code: "00000-000",
    street: "Street Name",
    address_number: "123",
    neighborhood: "Neighborhood Name",
    complement: "Apt 101",
    city: "City Name",
    state: "SP",
    country: "BR"

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

🔄 Flow

Initialization: SDK loads ThreatMetrix and generates Device ID
Authentication: CyberSource Device Data Collection
IP Collection: Multiple methods (Ipify, HTTPBin, WebRTC)
Send: Complete payload to payment API
3DS: If needed, opens modal for authentication
Result: Success or error callback

🛡️ Security

ThreatMetrix: Advanced device fingerprinting
CyberSource: Device Data Collection for 3DS
3DS 2.0: Strong authentication when needed
IP Detection: Multiple methods for maximum compatibility

📞 Support

For questions or issues:

Check browser console logs
Test with provided examples
Use authentication-test.html file for isolated debugging