Integration Overview

Quick Reference

WhatIntegration models for accepting payments

WhyPick the path that matches your control needs, UX goals, and timeline

Reading Time7 min

DifficultyBeginner

PrerequisitesAuthentication → Environment

Why this decision matters

The integration model you choose determines how card data flows, who handles 3DS, and how much A55 manages for you. Changing models later means re-architecture. Spend 7 minutes here to save weeks later.

Wrong choice	Consequence
H2H when you don't need full control	You take on card-data handling that A55 could manage for you
SDK when you need full server control	You fight the SDK instead of leveraging it
Checkout Page when you need pixel-perfect UX	You lose control over the payment experience

---

Comparison matrix

Criterion	H2H (Host-to-Host)	SDK (Embedded)	Checkout Page (Redirect)
Time to integrate	Weeks	Days	Hours
Card data handling	Your servers	SDK in browser — A55 secures it	A55 hosted page — fully managed
UX control	Full — every pixel is yours	High — native checkout, SDK handles 3DS	Limited — A55-hosted page
Who runs 3DS	You (handle url_3ds)	SDK (frictionless + challenge)	A55 (end-to-end)
Security	A55 encrypts and vaults all card data	A55 handles card capture and encryption	A55 manages everything end-to-end
Best for	Teams needing full server-side control	Native checkout with less 3DS work	Fastest launch, zero card-data handling

---

Decision tree

Quick rules

• Hours to launch? → Checkout Page
• Native UX, no card-data handling? → SDK
• Full server-side control? → H2H

---

1. H2H (Host-to-Host)

Your backend sends card data, customer fields, and 3DS payloads directly to A55.

You handle: Card collection, HTTPS transport, 3DS challenge redirect, webhook processing.

A55 handles: Acquirer routing, authorization, webhook delivery.

Strength	Trade-off
Full control over every step of the payment	You handle card data before passing it to A55
Custom retry logic and error handling	3DS challenge flow requires frontend work
Direct access to all API parameters	Longest integration timeline

---

2. SDK (Embedded Frontend)

Embed the A55 JavaScript SDK on your checkout page. It collects card data, handles 3DS, and reports the result.

You handle: Charge creation on backend, SDK initialization on frontend, webhook processing.

SDK handles: Card field rendering, device fingerprinting, 3DS frictionless/challenge routing, async callbacks.

Strength	Trade-off
Native checkout UX — the SDK renders inside your page	You integrate and test the SDK lifecycle
Card data never hits your servers — A55 handles it securely	Less flexibility than raw H2H
3DS handled automatically by the SDK	Requires frontend JavaScript integration

---

3. Checkout Page (Redirect)

Create a charge with minimal data, then redirect the payer to A55's hosted page. Card collection, 3DS, and payment completion happen there.

You handle: Charge creation, redirect, return URL handling, webhook processing.

A55 handles: Everything else — card capture, 3DS, payment completion, hosted UI.

Strength	Trade-off
Fastest launch — hours to production	Less control over payment UX
Zero card-data handling — A55 manages everything	Redirect takes user off your site
No frontend JavaScript required	Hosted page styling is A55-managed

---

Responsibilities summary

Responsibility	H2H	SDK	Checkout
Create charge on backend	You	You	You
Collect card data	You	SDK	A55
Handle 3DS challenges	You	SDK	A55
Process webhooks	You	You	You
Card data security	A55 encrypts and vaults	A55 handles in browser	A55 manages end-to-end
Frontend JavaScript	Not required	Required (SDK)	Not required

---

Integration quickstart

Regardless of model, the backend charge creation call is the same:

cURL

curl -s -X POST https://core-manager.a55.tech/api/v1/bank/wallet/charge/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_uuid": "YOUR_WALLET_UUID",
    "merchant_id": "YOUR_MERCHANT_UUID",
    "payer_name": "Jane Smith",
    "payer_email": "jane@example.com",
    "payer_tax_id": "12345678909",
    "payer_cell_phone": "+5511999999999",
    "installment_value": 250.00,
    "currency": "BRL",
    "due_date": "2026-12-31",
    "description": "Order #42",
    "type_charge": "credit_card",
    "webhook_url": "https://your-app.com/webhooks/a55"
  }'

Python

import requests

charge = requests.post(
    "https://core-manager.a55.tech/api/v1/bank/wallet/charge/",
    json={
        "wallet_uuid": "YOUR_WALLET_UUID",
        "merchant_id": "YOUR_MERCHANT_UUID",
        "payer_name": "Jane Smith",
        "payer_email": "jane@example.com",
        "payer_tax_id": "12345678909",
        "payer_cell_phone": "+5511999999999",
        "installment_value": 250.00,
        "currency": "BRL",
        "due_date": "2026-12-31",
        "description": "Order #42",
        "type_charge": "credit_card",
        "webhook_url": "https://your-app.com/webhooks/a55",
    },
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
    },
).json()

print(f"Charge UUID: {charge['charge_uuid']}")
print(f"Status: {charge['status']}")

JavaScript

const charge = await fetch(
  "https://core-manager.a55.tech/api/v1/bank/wallet/charge/",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      wallet_uuid: "YOUR_WALLET_UUID",
      merchant_id: "YOUR_MERCHANT_UUID",
      payer_name: "Jane Smith",
      payer_email: "jane@example.com",
      payer_tax_id: "12345678909",
      payer_cell_phone: "+5511999999999",
      installment_value: 250.0,
      currency: "BRL",
      due_date: "2026-12-31",
      description: "Order #42",
      type_charge: "credit_card",
      webhook_url: "https://your-app.com/webhooks/a55",
    }),
  }
).then(r => r.json());

console.log(`Charge UUID: ${charge.charge_uuid}`);
console.log(`Status: ${charge.status}`);

What happens after this call depends on your integration model:

• H2H: Include card object in the payload; handle url_3ds if returned.
• SDK: Use the returned charge_uuid to initialize the frontend SDK.
• Checkout Page: Include is_checkout: true; redirect the payer to the returned URL.

---

Webhooks are the source of truth

Regardless of integration model

Treat webhooks as authoritative for the final payment state. Show a "processing" state after submission until a webhook confirms the outcome. Terminal states (paid, error, canceled, refunded) do not transition further.

Show	When
Processing	After payment submission
Success	Webhook confirms paid
Failed	Webhook confirms error or canceled

Regardless of which integration model you choose, Visa Data Only can boost your approval rates by sharing enriched transaction data with issuers — without adding any friction. Square's pilot showed up to +646 basis points improvement across 6 million transactions.

All three integration methods support Data Only. Add data_only: true to your charge payload and include device_info.

Learn how to activate Data Only →

H2H guide →Full server-to-server integration with 3DS handling.SDK v2 guide →Embed the A55 SDK for native checkout with automatic 3DS.Checkout Page guide →Redirect to A55 hosted checkout — fastest integration.DataOnly →Highest approval rates via data sharing — no challenges.