Integration H2H

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

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

Enabling H2H Mode

To enable H2H mode and configure 3DS or non-3DS flows, please contact our technical team at [email protected]. Our team will assist with all necessary configurations to ensure a smooth integration.