Your First Charge in 5 Minutes

Quick Reference

WhatMake your first credit card charge on A55 sandbox

WhyValidate your integration setup end-to-end before writing production code

Reading Time5 min

DifficultyBeginner

PrerequisitesSandbox credentials (client_id + client_secret)

Overview

This guide walks you through the complete flow: authenticate, create a wallet, charge a credit card, and check the result. Every command runs against the sandbox — no real money moves.

Test Cards

Card Number	Brand	Scenario	Expected Status
`4111 1111 1111 1111`	Visa	Successful payment	confirmed
`4000 0000 0000 0002`	Visa	Card declined	declined
`4000 0000 0000 0069`	Visa	Processing error	error

Steps

Get your sandbox credentials

Email tech.services@a55.tech to request sandbox access. You will receive:

Credential	Description
`client_id`	OAuth2 client identifier
`client_secret`	OAuth2 client secret
`entity_uuid`	Your entity identifier
`merchant_uuid`	Your merchant identifier

Store them as environment variables:

export A55_CLIENT_ID="your_client_id"
export A55_CLIENT_SECRET="your_client_secret"

Get an access token

A55 uses OAuth2 client_credentials grant. Exchange your credentials for a bearer token.

cURL
Python
Node.js

curl -s -X POST "https://auth.a55.tech/oauth2/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials" \
-d "client_id=${A55_CLIENT_ID}" \
-d "client_secret=${A55_CLIENT_SECRET}" \
-d "scope=api/readwrite" | python3 -m json.tool

import os
import requests

try:
  response = requests.post(
      "https://auth.a55.tech/oauth2/token",
      data={
          "grant_type": "client_credentials",
          "client_id": os.environ["A55_CLIENT_ID"],
          "client_secret": os.environ["A55_CLIENT_SECRET"],
          "scope": "api/readwrite",
      },
  )
  response.raise_for_status()
  token = response.json()["access_token"]
  print(f"Token: {token[:20]}...")
except requests.RequestException as e:
  print(f"Authentication failed: {e}")
  raise

const fetch = require("node-fetch");

async function getToken() {
try {
  const res = await fetch("https://auth.a55.tech/oauth2/token", {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      grant_type: "client_credentials",
      client_id: process.env.A55_CLIENT_ID,
      client_secret: process.env.A55_CLIENT_SECRET,
      scope: "api/readwrite",
    }),
  });
  if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
  const { access_token } = await res.json();
  console.log("Token:", access_token.slice(0, 20) + "...");
  return access_token;
} catch (err) {
  console.error("Authentication failed:", err.message);
  throw err;
}
}

getToken();

Save the token:

export A55_ACCESS_TOKEN="eyJhbGciOiJSUzI1NiIs..."

Create a wallet

A wallet groups charges under a single entity. You need one before creating charges.

cURL
Python
Node.js

curl -s -X POST "https://sandbox.api.a55.tech/api/v1/bank/wallet/" \
-H "Authorization: Bearer ${A55_ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
  "name": "My First Wallet"
}' | python3 -m json.tool

import os
import requests

try:
  response = requests.post(
      "https://sandbox.api.a55.tech/api/v1/bank/wallet/",
      headers={"Authorization": f"Bearer {os.environ['A55_ACCESS_TOKEN']}"},
      json={"name": "My First Wallet"},
  )
  response.raise_for_status()
  wallet = response.json()
  print(f"Wallet UUID: {wallet['uuid']}")
except requests.RequestException as e:
  print(f"Wallet creation failed: {e}")
  raise

async function createWallet() {
try {
  const res = await fetch("https://sandbox.api.a55.tech/api/v1/bank/wallet/", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.A55_ACCESS_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ name: "My First Wallet" }),
  });
  if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
  const wallet = await res.json();
  console.log("Wallet UUID:", wallet.uuid);
  return wallet;
} catch (err) {
  console.error("Wallet creation failed:", err.message);
  throw err;
}
}

Response:

{
  "uuid": "wal_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "My First Wallet",
  "status": "active",
  "created_at": "2026-03-21T12:00:00Z"
}

Create a credit card charge

Send a POST to the charge endpoint with test card 4111 1111 1111 1111.

cURL
Python
Node.js

curl -s -X POST "https://sandbox.api.a55.tech/api/v1/bank/wallet/charge/" \
-H "Authorization: Bearer ${A55_ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
  "merchant_id": "YOUR_MERCHANT_UUID",
  "wallet_uuid": "YOUR_WALLET_UUID",
  "payer_name": "John Does Silva",
  "payer_email": "johndoes123@gmail.com",
  "description": "Quickstart test charge",
  "due_date": "2025-12-31",
  "installment_count": 1,
  "installment_value": 100.00,
  "currency": "BRL",
  "type_charge": "credit_card",
  "card_name": "John Does",
  "card_number": "4111111111111111",
  "card_expiry_year": "2030",
  "card_expiry_month": "12",
  "card_cvv": "123"
}' | python3 -m json.tool

import os
import requests

try:
  response = requests.post(
      "https://sandbox.api.a55.tech/api/v1/bank/wallet/charge/",
      headers={"Authorization": f"Bearer {os.environ['A55_ACCESS_TOKEN']}"},
      json={
          "merchant_id": "YOUR_MERCHANT_UUID",
          "wallet_uuid": "YOUR_WALLET_UUID",
          "payer_name": "John Does Silva",
          "payer_email": "johndoes123@gmail.com",
          "description": "Quickstart test charge",
          "due_date": "2025-12-31",
          "installment_count": 1,
          "installment_value": 100.00,
          "currency": "BRL",
          "type_charge": "credit_card",
          "card_name": "John Does",
          "card_number": "4111111111111111",
          "card_expiry_year": "2030",
          "card_expiry_month": "12",
          "card_cvv": "123",
      },
  )
  response.raise_for_status()
  charge = response.json()
  print(f"Charge UUID: {charge['charge_uuid']}")
  print(f"Status: {charge['status']}")
except requests.RequestException as e:
  print(f"Charge failed: {e}")
  raise

async function createCharge() {
try {
  const res = await fetch("https://sandbox.api.a55.tech/api/v1/bank/wallet/charge/", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.A55_ACCESS_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      merchant_id: "YOUR_MERCHANT_UUID",
      wallet_uuid: "YOUR_WALLET_UUID",
      payer_name: "John Does Silva",
      payer_email: "johndoes123@gmail.com",
      description: "Quickstart test charge",
      due_date: "2025-12-31",
      installment_count: 1,
      installment_value: 100.00,
      currency: "BRL",
      type_charge: "credit_card",
      card_name: "John Does",
      card_number: "4111111111111111",
      card_expiry_year: "2030",
      card_expiry_month: "12",
      card_cvv: "123",
    }),
  });
  if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
  const charge = await res.json();
  console.log("Charge UUID:", charge.charge_uuid);
  console.log("Status:", charge.status);
  return charge;
} catch (err) {
  console.error("Charge failed:", err.message);
  throw err;
}
}

Response:

{
  "charge_uuid": "a34f2499-2a40-40a5-8f5a-578002a88f51",
  "local_currency": 100.00,
  "currency": "BRL",
  "usd_currency": 18.52,
  "type": "credit_card",
  "date": "2026-03-25",
  "description": "Quickstart test charge",
  "due_date": "2025-12-31",
  "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": null,
  "is_async": false
}

Check charge status

Retrieve the charge to confirm its final status.

cURL
Python
Node.js

CHARGE_UUID="a34f2499-2a40-40a5-8f5a-578002a88f51"

curl -s -X GET "https://sandbox.api.a55.tech/api/v1/bank/wallet/charge/?charge_uuid=${CHARGE_UUID}" \
-H "Authorization: Bearer ${A55_ACCESS_TOKEN}" | python3 -m json.tool

import os
import requests

charge_uuid = "a34f2499-2a40-40a5-8f5a-578002a88f51"

try:
  response = requests.get(
      "https://sandbox.api.a55.tech/api/v1/bank/wallet/charge/",
      headers={"Authorization": f"Bearer {os.environ['A55_ACCESS_TOKEN']}"},
      params={"charge_uuid": charge_uuid},
  )
  response.raise_for_status()
  charge = response.json()
  print(f"Status: {charge['status']}")
except requests.RequestException as e:
  print(f"Status check failed: {e}")
  raise

async function checkStatus(chargeUuid) {
try {
  const url = new URL("https://sandbox.api.a55.tech/api/v1/bank/wallet/charge/");
  url.searchParams.set("charge_uuid", chargeUuid);
  const res = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.A55_ACCESS_TOKEN}` },
  });
  if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
  const charge = await res.json();
  console.log("Status:", charge.status);
  return charge;
} catch (err) {
  console.error("Status check failed:", err.message);
  throw err;
}
}

checkStatus("a34f2499-2a40-40a5-8f5a-578002a88f51");

What happens when you create a charge

A55 receives your charge request and validates all fields
The request is routed to the best available acquirer based on card BIN, currency, and merchant configuration
The acquirer processes the authorization with the card network (Visa/Mastercard)
A55 returns the authorization result synchronously
If you configured a webhook_url, A55 sends an asynchronous notification with the final status

Next Steps

Authentication →Token lifecycle, refresh strategies, and scopes Host-to-Host Integration →Full server-side integration guide Webhooks →Receive real-time payment notifications