Integration SDK

The A55Pay SDK provides a simple way to integrate 3DS and payment submission into your checkout flow. You provide the charge_uuid (from your backend) and user input (userData), and the SDK handles the rest by fetching the charge data automatically.

Payment Flow Diagram

sequenceDiagram
    autonumber
    participant Merchant as "🛒 Merchant"
    participant A55 as "💳 API A55"
    participant Script as "📜 3DS Script"
    participant Serve3DS as "🛡️ 3DS 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 (needed for script)
        deactivate A55
    end

    Merchant->>Script: Starts 3D Secure using charge_uuid
    Script->>Serve3DS: Processes and authenticates 3DS (force or not rquerid)
    activate Serve3DS

    alt Challenge required
        Serve3DS-->>Script: Responds — challenge is necessary
        Note right of Script: Additional authentication step needed
        Script->>Merchant: Shows 3DS challenge screen to customer
        Merchant-->>Script: Customer completes challenge (enters code, etc.)
    else No challenge required
        Serve3DS-->>Script: Responds — authentication status
        Note right of Script: No extra authentication was needed
    end
    deactivate Serve3DS

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

Example Payload

API Route

Endpoint: https://core-manager.a55.tech/api/v1/bank/wallet/charge/
Method: POST

Request

{
  "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"
}

Response

{
    "charge_uuid": "22222222-2222-2222-2222-222222222222",
    "local_currency": 100.0,
    "currency": "BRL",
    "usd_currency": 20.0,
    "eur_currency": 18.0,
    "type": "credit_card",
    "date": "2025-07-24",
    "description": "Sample purchase description",
    "due_date": "2025-12-31",
    "status": "issued",
    "message": null,
    "installment_count": 1,
    "installments": [
        {
            "local_currency": 100.0,
            "currency": "BRL",
            "usd_currency": 20.0,
            "eur_currency": 18.0,
            "due_date": "2025-12-31",
            "status": "issued",
            "installment_number": 1
        }
    ]
}

Usage Example

<!-- Add this to your checkout page -->
<script src="https://cdn.jsdelivr.net/npm/a55pay-sdk@latest"></script>
<script>
  // Example: charge_uuid from your backend
  const charge_uuid = '...';

  // Example: userData from your checkout form
  const userData = {
    holder: 'John Doe',
    number: '4111 1111 1111 1111',
    month: '12',
    year: '2028',
    cvc: '123',
    phone: '5511999999999',
    street1: 'Rua Exemplo',
    street2: '',
    city: 'São Paulo',
    state: 'SP',
    zipcode: '01234567',
    country: 'BR',
    device_ipaddress: '1.2.3.4' // (optional, can be fetched by SDK)
  };

  A55Pay.pay({
    selector: '#your-form', // CSS selector for the form or container
    charge_uuid, // This charge_uuid comes from the charge creation response
    userData,
    forceThreeds: false, // Proceed with payment even if 3DS fails
    onSuccess: function(result) {
      // Handle payment success
      console.log('Payment success:', result);
    },
    onError: function(error) {
      // Handle error
      console.log('Payment error:', error);
    },
    onReady: function() {
      // Optional: called when 3DS is ready
    }
  });
</script>

userData Fields

Field	Type	Required	Description
holder	string	Yes	Cardholder's full name
number	string	Yes	Card number (spaces allowed)
month	string	Yes	Expiry month (MM)
year	string	Yes	Expiry year (YYYY)
cvc	string	Yes	Card CVC/CVV
phone	string	Yes	Customer phone number (digits only preferred)
street1	string	Yes	Billing street address
street2	string	No	Billing address complement
city	string	Yes	Billing city
state	string	Yes	Billing state (2-letter code)
zipcode	string	Yes	Billing postal code (digits only preferred)
country	string	Yes	Country code (2-letter, e.g. 'BR')
device_ipaddress	string	Yes	Device IP address (optional, can be set by SDK)

charge_uuid

You only need to provide the charge_uuid (string) from your backend. The SDK will fetch all other required charge data automatically from the A55 API.

`forceThreeds`

The forceThreeds parameter is a boolean flag that controls the behavior of the SDK when 3DS authentication fails or is not supported.

Default: true
Description:
- When true, the SDK will stop the payment process if 3DS authentication fails or is not supported.
- When false, the SDK will proceed with the payment request even if 3DS authentication fails or is not supported.

Notes

The SDK will inject all required hidden fields for 3DS into the form/container you specify.
All callbacks (onSuccess, onError, onReady) are optional but recommended.
The SDK will handle the 3DS authentication and call your backend /pay endpoint automatically.
The backend payload will match your original API (see your reference.vue for details).
The SDK now only requires charge_uuid and userData—it will fetch the charge data for you.

HTML Example

Below is an example HTML file to test the A55Pay SDK integration:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Test A55Pay SDK Integration</title>
</head>
<body>
  <h1>Test A55Pay SDK Integration</h1>
  <form id="a55pay-form">
    <input value="4000000000000001" type="text" name="number" placeholder="Card Number" required><br>
    <input value="02" type="text" name="month" placeholder="Expiry Month (MM)" required><br>
    <input value="2032" type="text" name="year" placeholder="Expiry Year (YYYY)" required><br>
    <input value="123" type="text" name="cvc" placeholder="CVC" required><br>
    <input value="John Doe" type="text" name="holder" placeholder="Card Holder" required><br>
    <input value="5511999999999" type="text" name="phone" placeholder="Phone" required><br>
    <input value="Sample Street 123" type="text" name="street1" placeholder="Street" required><br>
    <input value="Sample City" type="text" name="city" placeholder="City" required><br>
    <input value="SC" type="text" name="state" placeholder="State" required><br>
    <input value="12345678" type="text" name="zipcode" placeholder="Zip Code" required><br>
    <input type="text" name="country" placeholder="Country" value="BR" required><br>
    <button type="submit">Pay</button>
  </form>
  <div id="result"></div>
  <script src="https://cdn.jsdelivr.net/npm/a55pay-sdk@latest"></script>
  <script>
    document.getElementById('a55pay-form').addEventListener('submit', function(e) {
      e.preventDefault();
      const form = e.target;
      const userData = {
        number: form.number.value,
        month: form.month.value,
        year: form.year.value,
        cvc: form.cvc.value,
        holder: form.holder.value,
        phone: form.phone.value,
        street1: form.street1.value,
        city: form.city.value,
        state: form.state.value,
        zipcode: form.zipcode.value,
        country: form.country.value
      };
      // Replace with a real charge_uuid for a real test
      const charge_uuid = '22222222-2222-2222-2222-222222222222';
      A55Pay.pay({
        selector: '#a55pay-form',
        charge_uuid,
        userData,
        forceThreeds: true,
        onSuccess: function(data) {
          document.getElementById('result').textContent = 'Success: ' + JSON.stringify(data);
        },
        onError: function(err) {
          document.getElementById('result').textContent = 'Error: ' + err.message;
        },
        onReady: function() {
          document.getElementById('result').textContent = 'Ready to pay!';
        }
      });
    });
  </script>
</body>
</html>