The Host-to-Host (H2H) integration mode allows businesses to directly connect with the Wallet Manager API for seamless transaction processing. This mode supports advanced features like 3DS authentication and provides flexibility for managing payment flows.

Payment Flow Diagram

sequenceDiagram
    participant Payer
    participant Merchant
    participant A55

    Note over Payer,Merchant: 🔄 Start of payment flow

    Payer ->> Merchant: Accesses website checkout
    activate Merchant
    Merchant ->> A55: POST /bank/wallet/charge/<br/>(card, customer, webhook_url, wallet_uuid)
    deactivate Merchant

    alt 🛡️ Bank requires 3DS authentication challenge
        rect rgb(225,245,254)
            Note over Merchant,A55: 3DS authentication flow
            activate A55
            A55 -->> Merchant: Returns url_3ds (status: pending)
            deactivate A55
            Merchant ->> Payer: Redirects/Modal to 3DS challenge
            Payer ->> A55: Completes 3DS challenge in url
            activate A55
            A55 -->> Merchant: Webhook with status<br/>(confirmed or error)
            deactivate A55
            Merchant -->> Payer: Displays transaction status
            Note over Payer,Merchant: 🏁 End of payment flow with 3ds
        end
    else ✅ Bank does not require 3DS authentication challenge
        rect rgb(255,249,196)
            Note over Merchant,A55: Immediate processing
            activate A55
            A55 -->> Merchant: Returns status<br/>(confirmed or error)
            deactivate A55
            Merchant -->> Payer: Displays transaction status
        end
    end

    Note over Payer,Merchant: 🏁 End of payment flow without 3ds

Request Example

API Route

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

Below is an example of a request payload for processing a transaction:

{
  "wallet_uuid": "11111111-2222-3333-4444-555555555555",
  "merchant_id": "66666666-7777-8888-9999-000000000000",
  "currency": "BRL",
  "installment_value": 250.75,
  "due_date": "2025-12-31",
  "description": "Compra de produto teste - Camiseta Premium",
  "type_charge": "credit_card",
  "card_name": "João da Silva",
  "card_number": "4111111111111111",
  "card_expiry_month": "07",
  "card_expiry_year": "2028",
  "card_cvv": "123",
  "webhook_url": "https://webhook-fake.com/abcdef1234567890"
}

{
  "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": "Description of the sample product",
      "quantity": 1,
      "total_amount": 100,
      "unit_amount": 100,
      "sku": "SAMPLE-SKU-123",
      "code": "SAMPLE-CODE-456"
    }
  ],
  "payer_address": {
    "street": "Sample Street",
    "address_number": "123",
    "complement": "Apt 101",
    "neighborhood": "Sample Neighborhood",
    "city": "Sample City",
    "state": "SP",
    "postal_code": "00000-000",
    "country": "BR"
  },
  "currency": "BRL",
  "installment_value": 100,
  "installment_count": 1,
  "due_date": "2025-12-31",
  "description": "Sample transaction description",
  "type_charge": "credit_card",
  "card_name": "John Doe",
  "card_number": "4111111111111111",
  "card_expiry_month": "12",
  "card_expiry_year": "2030",
  "card_cvv": "123",
  "webhook_url": "https://webhook-test.com/sample-webhook", // receives any status change of this charge
  "redirect_url": "https://example.com/redirect"
}

{
  "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": "Description of the sample product",
      "quantity": 1,
      "total_amount": 100,
      "unit_amount": 100,
      "sku": "SAMPLE-SKU-123",
      "code": "SAMPLE-CODE-456"
    }
  ],
  "payer_address": {
    "street": "Sample Street",
    "address_number": "123",
    "complement": "Apt 101",
    "neighborhood": "Sample Neighborhood",
    "city": "Sample City",
    "state": "SP",
    "postal_code": "00000-000",
    "country": "BR"
  },
  "currency": "BRL",
  "installment_value": 100,
  "installment_count": 1,
  "due_date": "2025-12-31",
  "description": "Sample transaction description",
  "type_charge": "credit_card",
  "card_name": "John Doe",
  "card_number": "4111111111111111", // DataOnly just Visa and Master
  "card_expiry_month": "12",
  "card_expiry_year": "2030",
  "card_cvv": "123",
  "device_info": {
    "ip_address": "192.168.0.1",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/90.0.0.0 Safari/537.36",
    "http_accept_content": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8",
    "http_browser_language": "en-US",
    "http_browser_java_enabled": true,
    "http_browser_javascript_enabled": true,
    "http_browser_color_depth": "24",
    "http_browser_screen_height": "1080",
    "http_browser_screen_width": "1920",
    "http_browser_time_difference": "-180",
    "http_accept_browser_value": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7"
  },
  "webhook_url": "https://webhook-test.com/sample-webhook",
}

{
  "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", // mandatory for 3ds
  "items": [ // mandatory for 3ds
    {
      "name": "Sample Product",
      "description": "Description of the sample product",
      "quantity": 1,
      "total_amount": 100,
      "unit_amount": 100,
      "sku": "SAMPLE-SKU-123",
      "code": "SAMPLE-CODE-456"
    }
  ],
  "payer_address": {
    "street": "Sample Street",
    "address_number": "123",
    "complement": "Apt 101",
    "neighborhood": "Sample Neighborhood",
    "city": "Sample City",
    "state": "SP",
    "postal_code": "00000-000",
    "country": "BR"
  },
  "currency": "BRL",
  "installment_value": 100,
  "installment_count": 1,
  "due_date": "2025-12-31",
  "description": "Sample transaction description",
  "type_charge": "credit_card",
  "card_name": "John Doe",
  "card_number": "4111111111111111",
  "card_expiry_month": "12",
  "card_expiry_year": "2030",
  "card_cvv": "123",
  "threeds_authentication": false, // not force 3DS
  "device_info": { // mandatory for 3ds
    "ip_address": "192.168.0.1",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/90.0.0.0 Safari/537.36",
    "http_accept_content": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8",
    "http_browser_language": "en-US",
    "http_browser_java_enabled": true,
    "http_browser_javascript_enabled": true,
    "http_browser_color_depth": "24",
    "http_browser_screen_height": "1080",
    "http_browser_screen_width": "1920",
    "http_browser_time_difference": "-180",
    "http_accept_browser_value": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7"
  },
  "webhook_url": "https://webhook-test.com/sample-webhook", // receives any status change of this charge
  "redirect_url": "https://example.com/redirect"
}

{
  "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", // mandatory for 3ds
  "items": [ // mandatory for 3ds
    {
      "name": "Sample Product",
      "description": "Description of the sample product",
      "quantity": 1,
      "total_amount": 100,
      "unit_amount": 100,
      "sku": "SAMPLE-SKU-123",
      "code": "SAMPLE-CODE-456"
    }
  ],
  "payer_address": {
    "street": "Sample Street",
    "address_number": "123",
    "complement": "Apt 101",
    "neighborhood": "Sample Neighborhood",
    "city": "Sample City",
    "state": "SP",
    "postal_code": "00000-000",
    "country": "BR"
  },
  "currency": "BRL",
  "installment_value": 100,
  "installment_count": 1,
  "due_date": "2025-12-31",
  "description": "Sample transaction description",
  "type_charge": "credit_card",
  "card_name": "John Doe",
  "card_number": "4111111111111111",
  "card_expiry_month": "12",
  "card_expiry_year": "2030",
  "card_cvv": "123",
  "threeds_authentication": true, // force 3DS
  "device_info": { // mandatory for 3ds
    "ip_address": "192.168.0.1",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/90.0.0.0 Safari/537.36",
    "http_accept_content": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8",
    "http_browser_language": "en-US",
    "http_browser_java_enabled": true,
    "http_browser_javascript_enabled": true,
    "http_browser_color_depth": "24",
    "http_browser_screen_height": "1080",
    "http_browser_screen_width": "1920",
    "http_browser_time_difference": "-180",
    "http_accept_browser_value": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7"
  },
  "webhook_url": "https://webhook-test.com/sample-webhook", // receives any status change of this charge
  "redirect_url": "https://example.com/redirect"
}

{
  "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": "+155599999999",
  "items": [
    {
      "name": "Test Product",
      "description": "This is a sample product for test purposes",
      "quantity": 1,
      "total_amount": 100.00,
      "unit_amount": 100.00,
      "sku": "TEST-SKU-001",
      "code": "TEST-CODE-001"
    }
  ],
  "payer_address": {
    "street": "Test Avenue",
    "address_number": "123",
    "complement": "Suite 456",
    "neighborhood": "Downtown",
    "city": "Testville",
    "state": "CA",
    "postal_code": "12345-678",
    "country": "US"
  },
  "currency": "BRL",
  "installment_value": 100.00,
  "installment_count": 1,
  "due_date": "2025-12-31",
  "description": "Test transaction using external 3DS authentication",
  "type_charge": "credit_card",
  "card_name": "John Doe",
  "card_number": "4111111111111111",
  "card_expiry_month": "12",
  "card_expiry_year": "2030",
  "card_cvv": "123",
  "threeds_external": {
    "eci": "05",                                  // Indicates successful 3DS authentication
    "request_id": "3ds-ext-req-987654321",        // Unique request ID
    "xid": "dXNlci10ZXN0LXhpbGwtYWJjMTIz",         // Sample base64-encoded XID
    "cavv": "AAABBIIFmAAAAAAAAAAAAAAAAA=",         // Sample base64-encoded CAVV
    "version": "2.2.0"                            // 3DS protocol version
  },
  "webhook_url": "https://webhook.example.com/payment-status",
  "redirect_url": "https://merchant.example.com/thank-you"
}

Important Notes

Mandatory Fields for 3DS: To use 3DS authentication, most of the fields in the request payload are mandatory. The more data you provide, the higher the chances of approval.
threeds_authenticationField: If this field is set to true, 3DS authentication becomes mandatory. The transaction will only proceed if it is successfully authenticated.
3DS Challenge Flow:
- If a 3DS challenge is required, the response will include:
```
{
   ... other attr ...
  "status": "pending", // status waiting for challenge
  "url_3ds": "https://confirmation.a55.tech/charge/791b390a-f3ce-4c50-90a1-3b813b59b455" // url to render in a modal
}
```
- Render the url_3ds in a modal and follow the flow. The final status will be sent to the webhook_url provided in the request.
Non-3DS Flow:
- If 3DS is not configured, the authorization request will be processed directly, and the response will include:
```
{
  ... other attr ...
  "status": "confirmed" // or "error"
}
```

📘 DataOnly – Visa & Mastercard

📋 Overview

DataOnly is authentication flow available for Visa and Mastercard, which allows merchants to send additional cardholder data to the issuer without requiring a challenge.

This flow can be used for both credit and debit cards, and its main benefit is improving approval rates in online transactions.

⚠️ Important: Since there is no challenge, there is no liability shift. The risk of fraud and chargebacks remains with the merchant.

🎯 Benefits

✅ Supports Debit and Credit (Visa and Mastercard)
✅ Increases Approval Rate by providing more data to the issuer
✅ Frictionless experience for the customer (no challenge)

⚠️ Risks

❌ No Liability Shift: in case of fraud, the merchant bears the chargeback
❌ Not all issuers accept DataOnly for debit – some may still enforce Challenge
❌ Requires a complete and accurate payload (address,, device_info, description, etc.) to maximize approval

A55Pay SDK - 3DS Device Data Collection

📋 Overview

The A55Pay.authentication function implements Device Data Collection (DDC) using CyberSource/Cardinal Commerce. It helps improve approval rates for 3D Secure (3DS) authentication by collecting device information in the background, following the official CyberSource documentation.

📦 Installation

Include the SDK directly in your checkout page:

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

🎯 Key Benefits

✅ Higher 3DS approval rates: Collects crucial device data
✅ Official implementation: 100% aligned with CyberSource docs
✅ Simple integration: Single function in the SDK
✅ Runs in background: Transparent to the end user
✅ Session ID ready: Returns sessionId for immediate use

🚀 How It Works

Integration Flow

sequenceDiagram
    participant Client as Client/Checkout
    participant SDK as A55Pay SDK
    participant Backend as A55 Backend
    participant CyberSource as CyberSource
    
    Client->>SDK: A55Pay.authentication()
    SDK->>Backend: POST /setup-authentication
    Backend->>SDK: access_token + collection_url
    SDK->>CyberSource: Device Data Collection
    CyberSource->>SDK: profile.completed
    SDK->>Client: sessionId
    Client->>Backend: Charge with device_info.session_id

1. Call SDK from Checkout

When the customer clicks Pay, call the SDK before processing the payment:

A55Pay.authentication({
  transactionReference: "transaction-uuid",
  cardBrand: "Visa",
  cardExpiryMonth: "08", 
  cardExpiryYear: "2029",
  cardNumber: "4111111111111111",
  onSuccess: function(result) {
    // Device Data Collection completed
    const sessionId = result.sessionId;
    // Use sessionId in the next step
  },
  onError: function(error) {
    console.error('Authentication error:', error);
  }
});

2. Use SessionId in Charge Request

After retrieving the sessionId, include it in your charge payload:

// Example charge payload
const chargePayload = {
  // ... other payment data
  device_info: {
    session_id: sessionId // Obtained from Device Data Collection
  }
  // ... rest of the payload
};

📝 API Reference

`A55Pay.authentication(config)`

Performs the CyberSource Device Data Collection to improve 3DS approval rates.

Config Parameters

Parameter	Type	Required	Description
`transactionReference`	String	Yes	Unique UUID of the transaction
`cardBrand`	String	Yes	Card brand (see list below)
`cardExpiryMonth`	String	Yes	Expiration month (e.g., `"08"`)
`cardExpiryYear`	String	Yes	Expiration year (e.g., `"2029"`)
`cardNumber`	String	Yes	Card number without spaces
`onSuccess`	Function	Yes	Success callback
`onError`	Function	Yes	Error callback

Supported Card Brands

Visa
MasterCard
AmericanExpress
Discover
JCB
DinersClub
Hipercard
Elo

Example Success Response

{
  sessionId: "71865b52-53a1-4cc3-a0ad-beab2d9b50e5",
  accessToken: "eyJhbGciOiJIUzI1NiI...",
  referenceId: "71865b52-53a1-4cc3-a0ad-beab2d9b50e5",
  deviceDataCollection: "completed"
}