Host-to-Host Integration

Quick Reference

WhatServer-to-server charge API

WhyMaximum control over retries, idempotency, and error handling

Reading Time20 min

DifficultyAdvanced

PrerequisitesAuthentication → Environment

Host-to-Host (H2H) is direct API integration: your backend calls A55 with card and order data. You retain full control over retries, idempotency, and error handling.

Why H2H (comparison)

Criterion	H2H	SDK	Checkout Page
Control level	Full	Partial	Minimal
Card data handling	You collect, A55 secures	Browser SDK collects, A55 secures	A55-hosted — fully managed
3DS management	You handle redirect	SDK handles	A55 handles
Security	A55 encrypts and tokenizes	A55 handles in browser	A55 manages end-to-end
Best for	Teams needing full control	Native checkout experience	Fastest launch

When to use

You need to collect card data on your servers before sending it to A55.
You need maximum server-side control over the charge lifecycle.
You will handle payer redirects when the API returns pending and action_url (3DS challenge or fingerprint collection).

Card fields (request body)

Field	Description
`card_name`	Cardholder name as printed on the card
`card_number`	Primary Account Number (PAN)
`card_expiry_month`	Expiry month (1–12)
`card_expiry_year`	Expiry year (four digits)
`card_cvv`	Card verification value

Technical flow

Step-by-step integration

Get an access token

curl -s -X POST "https://auth.a55.tech/oauth2/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials&client_id=$CLIENT_ID&client_secret=$CLIENT_SECRET"

import os, requests

resp = requests.post(
  "https://auth.a55.tech/oauth2/token",
  data={"grant_type": "client_credentials",
        "client_id": os.environ["CLIENT_ID"],
        "client_secret": os.environ["CLIENT_SECRET"]},
  headers={"Content-Type": "application/x-www-form-urlencoded"},
)
access_token = resp.json()["access_token"]

const resp = await fetch(
"https://auth.a55.tech/oauth2/token",
{
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: "grant_type=client_credentials"
    + "&client_id=" + process.env.CLIENT_ID
    + "&client_secret=" + process.env.CLIENT_SECRET,
}
);
const { access_token } = await resp.json();

data := url.Values{
  "grant_type":    {"client_credentials"},
  "client_id":     {os.Getenv("CLIENT_ID")},
  "client_secret": {os.Getenv("CLIENT_SECRET")},
}
resp, _ := http.PostForm(
  "https://auth.a55.tech/oauth2/token", data)
defer resp.Body.Close()
var tok struct{ AccessToken string `json:"access_token"` }
json.NewDecoder(resp.Body).Decode(&tok)

HttpRequest req = HttpRequest.newBuilder()
  .uri(URI.create("https://auth.a55.tech/oauth2/token"))
  .header("Content-Type", "application/x-www-form-urlencoded")
  .POST(HttpRequest.BodyPublishers.ofString(
      "grant_type=client_credentials&client_id=" + CLIENT_ID
      + "&client_secret=" + CLIENT_SECRET))
  .build();
HttpResponse<String> resp = HttpClient.newHttpClient()
  .send(req, HttpResponse.BodyHandlers.ofString());
String accessToken = new JSONObject(resp.body()).getString("access_token");

$ch = curl_init("https://auth.a55.tech/oauth2/token");
curl_setopt_array($ch, [
  CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/x-www-form-urlencoded"],
  CURLOPT_POSTFIELDS => http_build_query([
      "grant_type" => "client_credentials",
      "client_id" => getenv("CLIENT_ID"),
      "client_secret" => getenv("CLIENT_SECRET"),
  ]),
]);
$token = json_decode(curl_exec($ch))->access_token;

Build and send the charge

POST https://sandbox.api.a55.tech/api/v1/bank/wallet/charge/

curl -sS -X POST 'https://sandbox.api.a55.tech/api/v1/bank/wallet/charge/' \
-H 'Authorization: Bearer $ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: ord_001' \
-d '{
  "wallet_uuid": "00000000-0000-4000-8000-000000000001",
  "merchant_id": "merchant_123",
  "payer_name": "Jane Doe",
  "payer_email": "jane@example.com",
  "payer_cell_phone": "+5511999999999",
  "payer_tax_id": "12345678901",
  "items": [{"name": "Order", "quantity": 1, "value": 10000}],
  "payer_address": {"street": "Av. Paulista 1000", "city": "São Paulo", "state": "SP", "zip_code": "01310100", "country": "BR"},
  "currency": "BRL",
  "installment_value": 10000,
  "installment_count": 1,
  "due_date": "2026-12-31",
  "description": "H2H charge",
  "type_charge": "credit_card",
  "card_name": "JANE DOE",
  "card_number": "4111111111111111",
  "card_expiry_month": 12,
  "card_expiry_year": 2030,
  "card_cvv": "123",
  "reference_external_id": "ord_001",
  "threeds_authentication": false,
  "webhook_url": "https://merchant.example/webhooks/a55",
  "redirect_url": "https://merchant.example/return"
}'

import os, requests

r = requests.post(
  "https://sandbox.api.a55.tech/api/v1/bank/wallet/charge/",
  headers={
      "Authorization": f"Bearer {os.environ['ACCESS_TOKEN']}",
      "Content-Type": "application/json",
  },
  json={
      "wallet_uuid": "00000000-0000-4000-8000-000000000001",
      "merchant_id": "merchant_123",
      "payer_name": "Jane Doe", "payer_email": "jane@example.com",
      "payer_tax_id": "12345678901",
      "currency": "BRL", "installment_value": 10000, "installment_count": 1,
      "type_charge": "credit_card",
      "card_name": "JANE DOE", "card_number": "4111111111111111",
      "card_expiry_month": 12, "card_expiry_year": 2030, "card_cvv": "123",
      "reference_external_id": "ord_001",
      "threeds_authentication": False,
      "webhook_url": "https://merchant.example/webhooks/a55",
  },
  timeout=60,
)
print(r.status_code, r.json())

const res = await fetch(
"https://sandbox.api.a55.tech/api/v1/bank/wallet/charge/",
{
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ACCESS_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    wallet_uuid: "00000000-0000-4000-8000-000000000001",
    merchant_id: "merchant_123",
    payer_name: "Jane Doe", payer_email: "jane@example.com",
    payer_tax_id: "12345678901",
    currency: "BRL", installment_value: 10000, installment_count: 1,
    type_charge: "credit_card",
    card_name: "JANE DOE", card_number: "4111111111111111",
    card_expiry_month: 12, card_expiry_year: 2030, card_cvv: "123",
    reference_external_id: "ord_001",
    threeds_authentication: false,
    webhook_url: "https://merchant.example/webhooks/a55",
  }),
}
);
console.log(await res.json());

payload := map[string]interface{}{
  "wallet_uuid": "00000000-0000-4000-8000-000000000001",
  "type_charge": "credit_card",
  "card_name": "JANE DOE", "card_number": "4111111111111111",
  "card_expiry_month": 12, "card_expiry_year": 2030, "card_cvv": "123",
  "currency": "BRL", "installment_value": 10000, "installment_count": 1,
  "reference_external_id": "ord_001",
  "threeds_authentication": false,
  "webhook_url": "https://merchant.example/webhooks/a55",
}
body, _ := json.Marshal(payload)
req, _ := http.NewRequest("POST",
  "https://sandbox.api.a55.tech/api/v1/bank/wallet/charge/", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+os.Getenv("ACCESS_TOKEN"))
req.Header.Set("Content-Type", "application/json")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
io.Copy(os.Stdout, resp.Body)

String json = """
{"wallet_uuid":"00000000-0000-4000-8000-000000000001",
"type_charge":"credit_card","card_name":"JANE DOE",
"card_number":"4111111111111111","card_expiry_month":12,
"card_expiry_year":2030,"card_cvv":"123",
"currency":"BRL","installment_value":10000,"installment_count":1,
"reference_external_id":"ord_001","threeds_authentication":false,
"webhook_url":"https://merchant.example/webhooks/a55"}
""";
HttpRequest req = HttpRequest.newBuilder()
  .uri(URI.create("https://sandbox.api.a55.tech/api/v1/bank/wallet/charge/"))
  .header("Authorization", "Bearer " + System.getenv("ACCESS_TOKEN"))
  .header("Content-Type", "application/json")
  .POST(HttpRequest.BodyPublishers.ofString(json)).build();
HttpResponse<String> resp = HttpClient.newHttpClient()
  .send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(resp.body());

$payload = [
  "wallet_uuid" => "00000000-0000-4000-8000-000000000001",
  "type_charge" => "credit_card",
  "card_name" => "JANE DOE", "card_number" => "4111111111111111",
  "card_expiry_month" => 12, "card_expiry_year" => 2030, "card_cvv" => "123",
  "currency" => "BRL", "installment_value" => 10000, "installment_count" => 1,
  "reference_external_id" => "ord_001", "threeds_authentication" => false,
  "webhook_url" => "https://merchant.example/webhooks/a55",
];
$ch = curl_init("https://sandbox.api.a55.tech/api/v1/bank/wallet/charge/");
curl_setopt_array($ch, [
  CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
      "Authorization: Bearer " . getenv("ACCESS_TOKEN"),
      "Content-Type: application/json",
      "Idempotency-Key: ord_001"],
  CURLOPT_POSTFIELDS => json_encode($payload),
]);
echo curl_exec($ch);

Handle the response

The response always returns the full charge object. The key fields that change by outcome are status, action_url, and message.

Confirmed
Pending (action_url)
Error

{
  "charge_uuid": "a34f2499-2a40-40a5-8f5a-578002a88f51",
  "local_currency": 159.8,
  "currency": "EUR",
  "usd_currency": 185.59,
  "type": "credit_card",
  "date": "2026-04-01",
  "description": "#18770 Payments Cabo HDMI 2.1 Ultra 8K",
  "due_date": "2025-10-11",
  "status": "confirmed",
  "message": [],
  "installment_count": 1,
  "installments": [],
  "pix_payload": {},
  "qra_payload": {},
  "applepay_payload": {},
  "charge_payment_url": null,
  "action_url": "",
  "session_id": null,
  "subscription": {},
  "reference_external_id": "10ccf81a-1de7-4a3e-b86d-f3f685e8ee57",
  "is_async": false
}

When action_url is populated, the payer must be redirected to that URL to complete a 3DS challenge or fingerprint collection. After completion, the payer is automatically redirected to your redirect_url and a webhook is sent to webhook_url.

{
  "charge_uuid": "fe5e2c1e-b3fb-4cc4-bb28-004da37d5804",
  "local_currency": 159.8,
  "currency": "EUR",
  "usd_currency": 185.52,
  "type": "credit_card",
  "date": "2026-04-01",
  "description": "#18770 Payments Cabo HDMI 2.1 Ultra 8K",
  "due_date": "2025-10-11",
  "status": "pending",
  "message": null,
  "installment_count": 1,
  "installments": [],
  "pix_payload": {},
  "qra_payload": {},
  "applepay_payload": {},
  "charge_payment_url": null,
  "action_url": "https://acquirer.example/payment/69cd4a32e367...",
  "session_id": null,
  "subscription": {},
  "reference_external_id": "e4e3ec12-b51a-4ea2-aceb-2b41602a5a84",
  "is_async": false
}

Redirect the buyer to action_url. See 3D Secure for challenge handling details.

{
  "charge_uuid": "a34f2499-2a40-40a5-8f5a-578002a88f51",
  "local_currency": 159.8,
  "currency": "EUR",
  "usd_currency": 185.59,
  "type": "credit_card",
  "date": "2026-04-01",
  "description": "#18770 Payments Cabo HDMI 2.1 Ultra 8K",
  "due_date": "2025-10-11",
  "status": "error",
  "message": [
    {
      "code": "charge_error_issued",
      "description": "Missing required fields: remote_ip"
    }
  ],
  "installment_count": 1,
  "installments": [],
  "pix_payload": {},
  "qra_payload": {},
  "applepay_payload": {},
  "charge_payment_url": null,
  "action_url": "",
  "session_id": null,
  "subscription": {},
  "reference_external_id": "10ccf81a-1de7-4a3e-b86d-f3f685e8ee57",
  "is_async": false
}

Handle redirect (if pending)

If the response includes action_url, redirect the buyer to that URL. After the payer completes the action (3DS challenge or fingerprint), they are automatically redirected to your redirect_url. Always rely on the webhook for the final transaction status.

if (response.action_url) {
  window.location.href = response.action_url;
}

Confirm via webhook

Configure webhook_url so you receive async status updates even if the buyer closes the browser.

{
  "charge_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "paid",
  "transaction_reference": "txn_ref_001"
}

Test with sandbox cards

Card Number	Brand	Scenario	Expected Status
`4111 1111 1111 1111`	Visa	Successful payment	confirmed
`5500 0000 0000 0004`	Mastercard	Successful payment	confirmed
`4000 0000 0000 0002`	Visa	Card declined	declined
`4000 0000 0000 0101`	Visa	3DS challenge required	confirmed
`4000 0000 0000 0069`	Visa	Processing error	error
`5105 1051 0510 5100`	Mastercard	Insufficient funds	declined

Want higher approval rates?

Visa Data Only sends enriched transaction data to issuers through 3DS rails — without any challenge redirect. Square's pilot over 6 million transactions showed up to +646 basis points improvement.

If you already send device_info for 3DS, you already have the data. Set data_only: true instead of threeds_authentication: true.

Trade-off: no liability shift (merchant bears fraud). For high-volume, low-risk LATAM transactions, the approval rate gain typically exceeds fraud cost.

Learn how to activate Data Only →

3D Secure →Device data, frictionless vs challenge, validation.DataOnly →Highest approval rates via data sharing.Authentication →OAuth2 client credentials and Bearer tokens.Environment →Sandbox vs production endpoints and keys.

Quick Reference

Why H2H (comparison)​

When to use​

Card fields (request body)​

Technical flow​

Step-by-step integration​