Get wallet

Quick Reference

WhatRetrieve wallet details by UUID, email, or customer ID

WhyBalance verification, reconciliation, and multi-currency reporting

Reading Time3 min

DifficultyBeginner

PrerequisitesAuthentication → Wallet UUID or email or customer_id

GET/api/v1/bank/wallet/Bearer TokenRetrieve a wallet

When to use this endpoint

Without wallet lookup	With wallet lookup
Guess whether funds arrived	Verify exact balance before creating charges
No visibility into wallet state	Check wallet status, currency, and creation date
Manual reconciliation in spreadsheets	Automated reconciliation — compare expected vs. actual
Hard-coded wallet UUIDs everywhere	Dynamic lookup by email or customer_id
Cannot build multi-currency dashboards	Query each currency wallet and aggregate for reporting

---

Reconciliation flow

---

Authentication

Requires Bearer token. See Authentication.

Query parameters

Field	Type	Required	Description
wallet_uuid	string (UUID)	At least one	Direct wallet lookup by UUID
email	string	At least one	Find wallet by associated email
customer_id	string	At least one	Find wallet by your internal customer ID

Flexible lookup

Provide at least one parameter. You can combine them to narrow results — for example, ?customer_id=cust_12345&currency=BRL finds the BRL wallet for that customer.

---

Code examples

Lookup by wallet UUID

cURL

curl -s -G https://sandbox.api.a55.tech/api/v1/bank/wallet/ \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "wallet_uuid=f47ac10b-58cc-4372-a567-0e02b2c3d479"

Python

import requests
import os

token = os.environ["A55_API_TOKEN"]

wallet = requests.get(
    "https://sandbox.api.a55.tech/api/v1/bank/wallet/",
    params={"wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479"},
    headers={"Authorization": f"Bearer {token}"},
).json()

print(f"Wallet: {wallet['wallet_uuid']}")
print(f"Currency: {wallet['currency']}")
print(f"Email: {wallet['email']}")

JavaScript

const token = process.env.A55_API_TOKEN;

const params = new URLSearchParams({
  wallet_uuid: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
});

const wallet = await fetch(
  `https://sandbox.api.a55.tech/api/v1/bank/wallet/?${params}`,
  { headers: { Authorization: `Bearer ${token}` } }
).then((r) => r.json());

console.log(`Wallet: ${wallet.wallet_uuid}`);
console.log(`Currency: ${wallet.currency}`);
console.log(`Email: ${wallet.email}`);

Lookup by email

cURL

curl -s -G https://sandbox.api.a55.tech/api/v1/bank/wallet/ \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "email=financeiro@loja-sp.com.br"

Python

wallet = requests.get(
    "https://sandbox.api.a55.tech/api/v1/bank/wallet/",
    params={"email": "financeiro@loja-sp.com.br"},
    headers={"Authorization": f"Bearer {token}"},
).json()
print(f"Found wallet: {wallet['wallet_uuid']} ({wallet['currency']})")

JavaScript

const params = new URLSearchParams({ email: "financeiro@loja-sp.com.br" });

const wallet = await fetch(
  `https://sandbox.api.a55.tech/api/v1/bank/wallet/?${params}`,
  { headers: { Authorization: `Bearer ${token}` } }
).then((r) => r.json());

console.log(`Found wallet: ${wallet.wallet_uuid} (${wallet.currency})`);

Lookup by customer ID

cURL

curl -s -G https://sandbox.api.a55.tech/api/v1/bank/wallet/ \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "customer_id=cust_12345"

Python

wallet = requests.get(
    "https://sandbox.api.a55.tech/api/v1/bank/wallet/",
    params={"customer_id": "cust_12345"},
    headers={"Authorization": f"Bearer {token}"},
).json()
print(f"Found wallet: {wallet['wallet_uuid']} ({wallet['currency']})")

JavaScript

const params = new URLSearchParams({ customer_id: "cust_12345" });

const wallet = await fetch(
  `https://sandbox.api.a55.tech/api/v1/bank/wallet/?${params}`,
  { headers: { Authorization: `Bearer ${token}` } }
).then((r) => r.json());

console.log(`Found wallet: ${wallet.wallet_uuid} (${wallet.currency})`);

---

Response

Success (200 OK)

{
  "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "email": "financeiro@loja-sp.com.br",
  "customer_id": "cust_12345",
  "currency": "BRL",
  "date": "2026-03-15T10:30:00-03:00"
}

Response fields

Field	Type	Description
wallet_uuid	string (UUID)	Unique wallet identifier
email	string	Email associated with the wallet
customer_id	string	Your internal customer ID
currency	string	ISO 4217 currency code (BRL, MXN, CLP, ARS)
date	string (ISO 8601)	Wallet creation timestamp

Error response

{
  "error": "not_found",
  "message": "Wallet not found",
  "code": "errors.wallet.not_found"
}

Status	Code	Description	Resolution
400	validation_error	No query parameter provided	Supply at least one of wallet_uuid, email, or customer_id
401	unauthorized	Invalid or expired Bearer token	Refresh your access token
404	errors.wallet.not_found	No wallet matches the query	Verify the identifier or create a wallet first

---

Complete example — daily reconciliation script

A practical script that checks wallet state and compares it against your expected records:

cURL

#!/bin/bash
# Daily wallet reconciliation — run via cron
TOKEN="$A55_API_TOKEN"
BASE="https://sandbox.api.a55.tech/api/v1/bank/wallet/"

WALLETS=("cust_12345" "cust_67890" "cust_24680")

for CUST_ID in "${WALLETS[@]}"; do
  RESPONSE=$(curl -s -G "$BASE" \
    -H "Authorization: Bearer $TOKEN" \
    --data-urlencode "customer_id=$CUST_ID")

  WALLET_UUID=$(echo "$RESPONSE" | jq -r '.wallet_uuid')
  CURRENCY=$(echo "$RESPONSE" | jq -r '.currency')

  if [ "$WALLET_UUID" = "null" ]; then
    echo "MISSING: No wallet for customer $CUST_ID"
  else
    echo "OK: $CUST_ID → $WALLET_UUID ($CURRENCY)"
  fi
done

Python

import requests
import os

token = os.environ["A55_API_TOKEN"]
base = "https://sandbox.api.a55.tech/api/v1/bank/wallet/"
headers = {"Authorization": f"Bearer {token}"}

expected_wallets = {
    "cust_12345": "BRL",
    "cust_67890": "MXN",
    "cust_24680": "BRL",
}

reconciliation = {"matched": 0, "missing": 0, "mismatch": 0}

for customer_id, expected_currency in expected_wallets.items():
    response = requests.get(
        base,
        params={"customer_id": customer_id},
        headers=headers,
    )

    if response.status_code == 404:
        print(f"MISSING: {customer_id} — no wallet found")
        reconciliation["missing"] += 1
        continue

    wallet = response.json()
    if wallet["currency"] != expected_currency:
        print(f"MISMATCH: {customer_id} — expected {expected_currency}, got {wallet['currency']}")
        reconciliation["mismatch"] += 1
    else:
        print(f"OK: {customer_id} → {wallet['wallet_uuid']} ({wallet['currency']})")
        reconciliation["matched"] += 1

print(f"\nReconciliation: {reconciliation}")

JavaScript

const token = process.env.A55_API_TOKEN;
const base = "https://sandbox.api.a55.tech/api/v1/bank/wallet/";

const expectedWallets = {
  cust_12345: "BRL",
  cust_67890: "MXN",
  cust_24680: "BRL",
};

const results = { matched: 0, missing: 0, mismatch: 0 };

for (const [customerId, expectedCurrency] of Object.entries(expectedWallets)) {
  const params = new URLSearchParams({ customer_id: customerId });
  const response = await fetch(`${base}?${params}`, {
    headers: { Authorization: `Bearer ${token}` },
  });

  if (response.status === 404) {
    console.log(`MISSING: ${customerId} — no wallet found`);
    results.missing++;
    continue;
  }

  const wallet = await response.json();
  if (wallet.currency !== expectedCurrency) {
    console.log(`MISMATCH: ${customerId} — expected ${expectedCurrency}, got ${wallet.currency}`);
    results.mismatch++;
  } else {
    console.log(`OK: ${customerId} → ${wallet.wallet_uuid} (${wallet.currency})`);
    results.matched++;
  }
}

console.log("\nReconciliation:", results);

---

Tips

Cache wallet UUIDs

After the first lookup, cache the wallet_uuid in your database. Direct UUID lookups are faster than email or customer_id queries. Only fall back to email/customer_id lookup when the cached UUID returns a 404 (wallet was deleted and recreated).

Rate limits

Wallet lookups share the global rate limit of 100 requests/minute per token. For high-volume reconciliation, batch your lookups with a small delay between requests rather than firing all at once.

Don't poll for balance changes

Use webhooks to react to charge status changes in real-time. Reserve wallet lookups for scheduled reconciliation jobs, not as a substitute for event-driven architecture.

Create wallet →Set up a new wallet for a merchant and currency.Create charge →Process a payment on this wallet.List charges →Retrieve all charges for a wallet with filters and pagination.