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

1

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"

2

Get an access token

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

cURL

curl -s -X POST "https://auth.sandbox.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

Python

import os
import requests

try:
  response = requests.post(
      "https://auth.sandbox.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

Node.js

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

async function getToken() {
try {
  const res = await fetch("https://auth.sandbox.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..."

3

Create a wallet

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

cURL

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

Python

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

Node.js

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

4

Create a credit card charge

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

cURL

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 '{
  "amount": "100.00",
  "currency": "BRL",
  "type_charge": "credit_card",
  "card": {
    "number": "4111111111111111",
    "holder_name": "TEST CARDHOLDER",
    "expiration_month": "12",
    "expiration_year": "2030",
    "cvv": "123"
  },
  "payer": {
    "name": "Test User",
    "email": "test@example.com",
    "document": "12345678909",
    "document_type": "CPF"
  },
  "description": "Quickstart test charge"
}' | python3 -m json.tool

Python

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={
          "amount": "100.00",
          "currency": "BRL",
          "type_charge": "credit_card",
          "card": {
              "number": "4111111111111111",
              "holder_name": "TEST CARDHOLDER",
              "expiration_month": "12",
              "expiration_year": "2030",
              "cvv": "123",
          },
          "payer": {
              "name": "Test User",
              "email": "test@example.com",
              "document": "12345678909",
              "document_type": "CPF",
          },
          "description": "Quickstart test charge",
      },
  )
  response.raise_for_status()
  charge = response.json()
  print(f"Charge UUID: {charge['uuid']}")
  print(f"Status: {charge['status']}")
except requests.RequestException as e:
  print(f"Charge failed: {e}")
  raise

Node.js

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({
      amount: "100.00",
      currency: "BRL",
      type_charge: "credit_card",
      card: {
        number: "4111111111111111",
        holder_name: "TEST CARDHOLDER",
        expiration_month: "12",
        expiration_year: "2030",
        cvv: "123",
      },
      payer: {
        name: "Test User",
        email: "test@example.com",
        document: "12345678909",
        document_type: "CPF",
      },
      description: "Quickstart test charge",
    }),
  });
  if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
  const charge = await res.json();
  console.log("Charge UUID:", charge.uuid);
  console.log("Status:", charge.status);
  return charge;
} catch (err) {
  console.error("Charge failed:", err.message);
  throw err;
}
}

Response:

{
  "uuid": "chg_f1e2d3c4-b5a6-7890-fedc-ba0987654321",
  "status": "confirmed",
  "amount": "100.00",
  "currency": "BRL",
  "type_charge": "credit_card",
  "created_at": "2026-03-21T12:01:00Z"
}

5

Check charge status

Retrieve the charge to confirm its final status.

cURL

CHARGE_UUID="chg_f1e2d3c4-b5a6-7890-fedc-ba0987654321"

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

Python

import os
import requests

charge_uuid = "chg_f1e2d3c4-b5a6-7890-fedc-ba0987654321"

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

Node.js

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("chg_f1e2d3c4-b5a6-7890-fedc-ba0987654321");

What happens when you create a charge

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

Next Steps

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