Create wallet

Quick Reference

WhatCreate a wallet scoped to a merchant and currency

WhyWallets are the foundation — no wallet, no charges, no payments

Reading Time5 min

DifficultyBeginner

PrerequisitesAuthentication → Entity UUID → Customer ID

POST/api/v1/bank/wallet/Bearer TokenCreate a new wallet

When to use this endpoint

Without a wallet	With a wallet
Cannot process any charges	Accept payments via credit card, PIX, Boleto, SPEI, and 8 more methods
No balance tracking	Real-time balance per merchant per currency
No settlement container	Automatic settlement grouping and payout
No API credentials for the merchant	Optional auto-generated `client_id` / `client_secret` for merchant self-service
Cannot separate funds by currency	Isolated BRL, MXN, CLP, ARS wallets for clean multi-currency accounting

Entity hierarchy

Authentication

Requires Bearer token. See Authentication.

Request body

Field	Type	Required	Description
`entity_uuid`	string (UUID)	Yes	Account entity identifier — your company's UUID
`customer_id`	string	Yes	Internal customer ID in your system
`currency`	string	Yes	ISO 4217 currency code: `BRL`, `MXN`, `CLP`, or `ARS`
`name`	string	Yes	Wallet display name (shown in dashboard and reports)
`email`	string	Yes	Email address associated with this wallet
`create_credentials`	boolean	Yes	`true` to generate OAuth `client_id` and `client_secret` for this wallet
`merchant_uuid`	string	No	Associate this wallet with an existing merchant. Omit to auto-create

Code examples

cURL
Python
JavaScript

curl -s -X POST https://core-manager.a55.tech/api/v1/bank/wallet/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "customer_id": "cust_12345",
    "currency": "BRL",
    "name": "Loja São Paulo — BRL",
    "email": "financeiro@loja-sp.com.br",
    "create_credentials": true,
    "merchant_uuid": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
  }'

import requests
import os

token = os.environ["A55_API_TOKEN"]

wallet = requests.post(
    "https://core-manager.a55.tech/api/v1/bank/wallet/",
    json={
        "entity_uuid": "550e8400-e29b-41d4-a716-446655440000",
        "customer_id": "cust_12345",
        "currency": "BRL",
        "name": "Loja São Paulo — BRL",
        "email": "financeiro@loja-sp.com.br",
        "create_credentials": True,
        "merchant_uuid": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    },
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
    },
).json()

print(f"Wallet: {wallet['wallet_uuid']}")
if wallet.get("credentials"):
    print(f"Client ID:     {wallet['credentials']['client_id']}")
    print(f"Client Secret: {wallet['credentials']['client_secret']}")
    print(f"Grant Type:    {wallet['credentials']['grant_type']}")
    print(f"Scopes:        {', '.join(wallet['credentials']['scopes'])}")

const token = process.env.A55_API_TOKEN;

const wallet = await fetch(
  "https://core-manager.a55.tech/api/v1/bank/wallet/",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      entity_uuid: "550e8400-e29b-41d4-a716-446655440000",
      customer_id: "cust_12345",
      currency: "BRL",
      name: "Loja São Paulo — BRL",
      email: "financeiro@loja-sp.com.br",
      create_credentials: true,
      merchant_uuid: "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    }),
  }
).then((r) => r.json());

console.log(`Wallet: ${wallet.wallet_uuid}`);
if (wallet.credentials) {
  console.log(`Client ID:     ${wallet.credentials.client_id}`);
  console.log(`Client Secret: ${wallet.credentials.client_secret}`);
  console.log(`Grant Type:    ${wallet.credentials.grant_type}`);
  console.log(`Scopes:        ${wallet.credentials.scopes.join(", ")}`);
}

Response

Success (200 OK)

When create_credentials: true, the response includes a credentials object with OAuth keys scoped to this wallet.

{
  "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "entity_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "merchant_uuid": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "customer_id": "cust_12345",
  "currency": "BRL",
  "name": "Loja São Paulo — BRL",
  "email": "financeiro@loja-sp.com.br",
  "credentials": {
    "client_id": "3f8a2b1c-9d4e-5f6a-7b8c-0d1e2f3a4b5c",
    "client_secret": "sk_live_a55_7k9m2nP4qR6sT8uV0wX1yZ3",
    "grant_type": "client_credentials",
    "scopes": [
      "wallet:read",
      "wallet:write",
      "charge:create",
      "charge:read"
    ]
  }
}

Response fields

Field	Type	Description
`wallet_uuid`	string (UUID)	Unique wallet identifier — use this in all charge and balance calls
`entity_uuid`	string (UUID)	Parent entity
`merchant_uuid`	string (UUID)	Associated merchant
`customer_id`	string	Your internal customer ID
`currency`	string	ISO 4217 currency code
`name`	string	Wallet display name
`email`	string	Wallet email
`credentials`	object	Present only when `create_credentials: true`
`credentials.client_id`	string	OAuth client ID for Cognito token exchange
`credentials.client_secret`	string	OAuth client secret — store securely, shown only once
`credentials.grant_type`	string	Always `client_credentials`
`credentials.scopes`	string[]	Permitted API scopes for this wallet

Error response

{
  "error": "validation_error",
  "message": "Wallet already exists for this merchant and currency",
  "code": "errors.wallet.already_exists"
}

Status	Code	Description	Resolution
400	`validation_error`	Missing or invalid fields	Check required fields and types
401	`unauthorized`	Invalid or expired Bearer token	Refresh your access token
409	`errors.wallet.already_exists`	A wallet for this merchant + currency already exists	Use the existing wallet or choose a different currency

Complete example — multi-currency setup

Create wallets for a merchant that operates in Brazil and Mexico:

cURL
Python
JavaScript

# BRL wallet
curl -s -X POST https://core-manager.a55.tech/api/v1/bank/wallet/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "customer_id": "cust_12345",
    "currency": "BRL",
    "name": "LatAm Store — BRL",
    "email": "finance@latamstore.com",
    "create_credentials": true
  }'

# MXN wallet (same entity, same customer)
curl -s -X POST https://core-manager.a55.tech/api/v1/bank/wallet/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "customer_id": "cust_12345",
    "currency": "MXN",
    "name": "LatAm Store — MXN",
    "email": "finance@latamstore.com",
    "create_credentials": false
  }'

import requests
import os

token = os.environ["A55_API_TOKEN"]
base = "https://core-manager.a55.tech/api/v1/bank/wallet/"
headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}

for currency in ["BRL", "MXN"]:
    wallet = requests.post(
        base,
        json={
            "entity_uuid": "550e8400-e29b-41d4-a716-446655440000",
            "customer_id": "cust_12345",
            "currency": currency,
            "name": f"LatAm Store — {currency}",
            "email": "finance@latamstore.com",
            "create_credentials": currency == "BRL",
        },
        headers=headers,
    ).json()
    print(f"{currency} wallet: {wallet['wallet_uuid']}")

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

for (const currency of ["BRL", "MXN"]) {
  const wallet = await fetch(base, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      entity_uuid: "550e8400-e29b-41d4-a716-446655440000",
      customer_id: "cust_12345",
      currency,
      name: `LatAm Store — ${currency}`,
      email: "finance@latamstore.com",
      create_credentials: currency === "BRL",
    }),
  }).then((r) => r.json());
  console.log(`${currency} wallet: ${wallet.wallet_uuid}`);
}

Tips

Store credentials immediately

When create_credentials: true, the client_secret is returned only once. Store it in a secrets manager (AWS Secrets Manager, HashiCorp Vault, Azure Key Vault) immediately after creation. A55 cannot retrieve it later — you would need to rotate credentials.

One wallet per merchant per currency

A55 enforces a unique constraint on merchant_uuid + currency. If your merchant operates in both BRL and MXN, create two wallets. This keeps balances, settlements, and reporting cleanly separated by currency.

Credentials vs. platform token

Wallet credentials let the merchant call the API directly (e.g., create charges, check balance). Your platform token (entity-level) can operate on all wallets. Choose based on your architecture: centralized platform calls vs. delegated merchant access.

Get wallet →Retrieve wallet details, balance, and status.Create charge →Process your first payment on this wallet.Webhooks →Receive real-time notifications for charges and settlements.

Quick Reference

When to use this endpoint​

Entity hierarchy​

Authentication​

Request body​

Code examples​

Response​

Success (200 OK)​

Response fields​

Error response​

Complete example — multi-currency setup​

Tips​