创建钱包

Quick Reference

What创建绑定商户和货币的钱包

Why钱包是基础——没有钱包，就无法收费，无法收款

Reading Time5 分钟

Difficulty初级

Prerequisites身份验证 → 实体 UUID → 客户 ID

POST/api/v1/bank/wallet/Bearer Token创建新钱包

何时使用此端点

没有钱包	有钱包
无法处理任何收费	通过信用卡、PIX、Boleto、SPEI 等 8 种以上方式收款
没有余额跟踪	按商户按货币实时查看余额
没有结算容器	自动结算分组和付款
商户没有 API 凭证	可选自动生成 `client_id` / `client_secret` 供商户自助使用
无法按货币隔离资金	独立的 BRL、MXN、CLP、ARS 钱包，实现清晰的多币种账务

实体层级

身份验证

需要 Bearer 令牌。请参阅身份验证。

请求体

字段	类型	必填	说明
`entity_uuid`	string (UUID)	是	账户实体标识符——您公司的 UUID
`customer_id`	string	是	您系统中的内部客户 ID
`currency`	string	是	ISO 4217 货币代码：`BRL`、`MXN`、`CLP` 或 `ARS`
`name`	string	是	钱包显示名称（在仪表板和报表中展示）
`email`	string	是	与此钱包关联的邮箱地址
`create_credentials`	boolean	是	`true` 为此钱包生成 OAuth `client_id` 和 `client_secret`
`merchant_uuid`	string	否	将此钱包关联到现有商户。省略则自动创建

代码示例

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": "圣保罗门店——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": "圣保罗门店——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_uuid']}")
if wallet.get("credentials"):
    print(f"客户端 ID：    {wallet['credentials']['client_id']}")
    print(f"客户端密钥：   {wallet['credentials']['client_secret']}")
    print(f"授权类型：     {wallet['credentials']['grant_type']}")
    print(f"权限范围：     {', '.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: "圣保罗门店——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_uuid}`);
if (wallet.credentials) {
  console.log(`客户端 ID：    ${wallet.credentials.client_id}`);
  console.log(`客户端密钥：   ${wallet.credentials.client_secret}`);
  console.log(`授权类型：     ${wallet.credentials.grant_type}`);
  console.log(`权限范围：     ${wallet.credentials.scopes.join(", ")}`);
}

响应

成功 (200 OK)

当 create_credentials: true 时，响应包含一个 credentials 对象，其中含有此钱包专属的 OAuth 密钥。

{
  "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": "圣保罗门店——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"
    ]
  }
}

响应字段

字段	类型	说明
`wallet_uuid`	string (UUID)	钱包唯一标识符——在所有收费和余额调用中使用
`entity_uuid`	string (UUID)	父实体
`merchant_uuid`	string (UUID)	关联商户
`customer_id`	string	您的内部客户 ID
`currency`	string	ISO 4217 货币代码
`name`	string	钱包显示名称
`email`	string	钱包邮箱
`credentials`	object	仅在 `create_credentials: true` 时返回
`credentials.client_id`	string	用于 Cognito 令牌交换的 OAuth 客户端 ID
`credentials.client_secret`	string	OAuth 客户端密钥——请安全存储，仅显示一次
`credentials.grant_type`	string	始终为 `client_credentials`
`credentials.scopes`	string[]	此钱包允许的 API 权限范围

错误响应

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

状态码	错误码	说明	解决方法
400	`validation_error`	缺少或无效的字段	检查必填字段和类型
401	`unauthorized`	无效或过期的 Bearer 令牌	刷新您的访问令牌
409	`errors.wallet.already_exists`	此商户和货币的钱包已存在	使用现有钱包或选择其他货币

完整示例——多币种设置

为在巴西和墨西哥运营的商户创建钱包：

cURL
Python
JavaScript

# 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": "拉美商店——BRL",
    "email": "finance@latamstore.com",
    "create_credentials": true
  }'

# MXN 钱包（相同实体、相同客户）
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": "拉美商店——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"拉美商店——{currency}",
            "email": "finance@latamstore.com",
            "create_credentials": currency == "BRL",
        },
        headers=headers,
    ).json()
    print(f"{currency} 钱包：{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: `拉美商店——${currency}`,
      email: "finance@latamstore.com",
      create_credentials: currency === "BRL",
    }),
  }).then((r) => r.json());
  console.log(`${currency} 钱包：${wallet.wallet_uuid}`);
}

提示

请立即存储凭证

当 create_credentials: true 时，client_secret 仅返回一次。创建后请立即将其存储到密钥管理器（AWS Secrets Manager、HashiCorp Vault、Azure Key Vault）中。A55 之后无法再次获取——您需要轮换凭证。

每个商户每种货币一个钱包

A55 对 merchant_uuid + currency 强制执行唯一约束。如果您的商户同时运营 BRL 和 MXN，请创建两个钱包。这可以按货币清晰地隔离余额、结算和报表。

凭证与平台令牌的区别

钱包凭证允许商户直接调用 API（例如创建收费、查看余额）。您的平台令牌（实体级别）可以操作所有钱包。请根据您的架构选择：集中式平台调用 vs. 委托式商户访问。

查询钱包 →获取钱包详情、余额和状态。创建收费 →在此钱包上处理您的第一笔付款。Webhook 概述 →接收收费和结算的实时通知。

Quick Reference

何时使用此端点​

实体层级​

身份验证​

请求体​

代码示例​

响应​

成功 (200 OK)​

响应字段​

错误响应​

完整示例——多币种设置​

提示​