Criar carteira

Quick Reference

WhatCriar uma carteira vinculada a um comerciante e moeda

WhyCarteiras são a base — sem carteira, sem cobranças, sem pagamentos

Reading Time5 min

DifficultyBeginner

PrerequisitesAutenticação → UUID da Entidade → ID do Cliente

POST/api/v1/bank/wallet/Bearer TokenCriar uma nova carteira

Quando usar este endpoint

Sem carteira	Com carteira
Não é possível processar nenhuma cobrança	Aceite pagamentos via cartão de crédito, PIX, Boleto, SPEI e mais 8 métodos
Sem acompanhamento de saldo	Saldo em tempo real por comerciante por moeda
Sem contêiner de liquidação	Agrupamento automático de liquidação e repasse
Sem credenciais de API para o comerciante	`client_id` / `client_secret` opcionais gerados automaticamente para autoatendimento do comerciante
Não é possível separar fundos por moeda	Carteiras isoladas em BRL, MXN, CLP, ARS para contabilidade multi-moeda organizada

Hierarquia de entidades

Autenticação

Requer token Bearer. Veja Autenticação.

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`entity_uuid`	string (UUID)	Sim	Identificador da entidade da conta — o UUID da sua empresa
`customer_id`	string	Sim	ID interno do cliente no seu sistema
`currency`	string	Sim	Código de moeda ISO 4217: `BRL`, `MXN`, `CLP` ou `ARS`
`name`	string	Sim	Nome de exibição da carteira (exibido no painel e relatórios)
`email`	string	Sim	Endereço de e-mail associado a esta carteira
`create_credentials`	boolean	Sim	`true` para gerar `client_id` e `client_secret` OAuth para esta carteira
`merchant_uuid`	string	Não	Associar esta carteira a um comerciante existente. Omita para criar automaticamente

Exemplos de código

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(", ")}`);
}

Resposta

Sucesso (200 OK)

Quando create_credentials: true, a resposta inclui um objeto credentials com chaves OAuth com escopo para esta carteira.

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

Campos da resposta

Campo	Tipo	Descrição
`wallet_uuid`	string (UUID)	Identificador único da carteira — use em todas as chamadas de cobrança e saldo
`entity_uuid`	string (UUID)	Entidade pai
`merchant_uuid`	string (UUID)	Comerciante associado
`customer_id`	string	Seu ID interno do cliente
`currency`	string	Código de moeda ISO 4217
`name`	string	Nome de exibição da carteira
`email`	string	E-mail da carteira
`credentials`	object	Presente apenas quando `create_credentials: true`
`credentials.client_id`	string	ID do cliente OAuth para troca de token via Cognito
`credentials.client_secret`	string	Segredo do cliente OAuth — armazene com segurança, exibido apenas uma vez
`credentials.grant_type`	string	Sempre `client_credentials`
`credentials.scopes`	string[]	Escopos de API permitidos para esta carteira

Resposta de erro

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

Status	Código	Descrição	Resolução
400	`validation_error`	Campos ausentes ou inválidos	Verifique os campos obrigatórios e seus tipos
401	`unauthorized`	Token Bearer inválido ou expirado	Renove seu token de acesso
409	`errors.wallet.already_exists`	Já existe uma carteira para este comerciante + moeda	Use a carteira existente ou escolha uma moeda diferente

Exemplo completo — configuração multi-moeda

Crie carteiras para um comerciante que opera no Brasil e no México:

cURL
Python
JavaScript

# Carteira BRL
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
  }'

# Carteira MXN (mesma entidade, mesmo cliente)
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}`);
}

Dicas

Armazene as credenciais imediatamente

Quando create_credentials: true, o client_secret é retornado apenas uma vez. Armazene-o em um gerenciador de segredos (AWS Secrets Manager, HashiCorp Vault, Azure Key Vault) imediatamente após a criação. A A55 não pode recuperá-lo posteriormente — você precisaria rotacionar as credenciais.

Uma carteira por comerciante por moeda

A A55 impõe uma restrição de unicidade em merchant_uuid + currency. Se seu comerciante opera em BRL e MXN, crie duas carteiras. Isso mantém saldos, liquidações e relatórios separados de forma organizada por moeda.

Credenciais vs. token da plataforma

As credenciais da carteira permitem que o comerciante chame a API diretamente (ex.: criar cobranças, consultar saldo). Seu token de plataforma (nível de entidade) pode operar em todas as carteiras. Escolha conforme sua arquitetura: chamadas centralizadas pela plataforma vs. acesso delegado ao comerciante.

Consultar carteira →Recupere detalhes, saldo e status da carteira.Criar cobrança →Processe seu primeiro pagamento nesta carteira.Webhooks →Receba notificações em tempo real para cobranças e liquidações.

Quick Reference

Quando usar este endpoint​

Hierarquia de entidades​

Autenticação​

Corpo da requisição​

Exemplos de código​

Resposta​

Sucesso (200 OK)​

Campos da resposta​

Resposta de erro​

Exemplo completo — configuração multi-moeda​

Dicas​