PIX 转账

POST/api/v1/bank/wallet/transfer/pix/Bearer Token

---

请求头

请求头	值	必填
Authorization	Bearer {A55_ACCESS_TOKEN}	是
Content-Type	application/json	是
Idempotency-Key（幂等键）	UUID v4	建议

请求体

字段	类型	必填	说明
wallet_uuid	string (UUID)	是	转账来源钱包
amount	number	是	转账金额，单位为 BRL（例如 500.00）
currency	string	是	必须为 BRL
pix_key_type	string	是	cpf、cnpj、email、phone、random_key
pix_key	string	是	与类型对应的 PIX 密钥值
recipient_name	string	是	收款人全名
recipient_tax_id	string	是	收款人 CPF 或 CNPJ
description	string	否	转账描述
reference_id	string	否	您的内部参考号，用于对账

---

响应字段

字段	类型	说明
transfer_uuid	string	唯一转账标识符
status	string	processing、completed、failed
amount	number	转账金额
currency	string	BRL
pix_key_type	string	使用的 PIX 密钥类型
pix_key	string	目标 PIX 密钥
recipient_name	string	已确认的收款人姓名
created_at	string	ISO 8601 创建时间戳
completed_at	string	ISO 8601 完成时间戳（可用时）

---

HTTP 状态码

状态码	说明
200	转账发起成功
400	PIX 密钥无效或缺少必填字段
401	Bearer Token（持有者令牌）无效或已过期
403	权限不足或钱包余额不足
404	钱包未找到
409	重复转账（相同的 Idempotency-Key）
422	验证错误（密钥类型无效、金额无效）
429	超出速率限制
500	服务器内部错误 - 请使用指数退避重试

---

代码示例

cURL

curl -s -X POST https://core-manager.a55.tech/api/v1/bank/wallet/transfer/pix/ \
  -H "Authorization: Bearer $A55_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 770e8400-e29b-41d4-a716-446655440002" \
  -d '{
    "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "amount": 500.00,
    "currency": "BRL",
    "pix_key_type": "cpf",
    "pix_key": "123.456.789-09",
    "recipient_name": "张三",
    "recipient_tax_id": "123.456.789-09",
    "description": "供应商付款 #2048",
    "reference_id": "PAY-2048"
  }'

Python

import requests
import os

token = os.environ["A55_ACCESS_TOKEN"]
base = os.environ.get("A55_API_URL", "https://core-manager.a55.tech")

try:
    response = requests.post(
        f"{base}/api/v1/bank/wallet/transfer/pix/",
        json={
            "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
            "amount": 500.00,
            "currency": "BRL",
            "pix_key_type": "cpf",
            "pix_key": "123.456.789-09",
            "recipient_name": "张三",
            "recipient_tax_id": "123.456.789-09",
            "description": "供应商付款 #2048",
            "reference_id": "PAY-2048",
        },
        headers={
            "Authorization": f"Bearer {token}",
            "Content-Type": "application/json",
            "Idempotency-Key": "770e8400-e29b-41d4-a716-446655440002",
        },
    )
    response.raise_for_status()
    transfer = response.json()
    print(f"转账：{transfer['transfer_uuid']}——状态：{transfer['status']}")
except requests.exceptions.HTTPError as e:
    print(f"HTTP {e.response.status_code}: {e.response.json()}")
except requests.exceptions.RequestException as e:
    print(f"请求失败：{e}")

Node.js

const token = process.env.A55_ACCESS_TOKEN;
const base = process.env.A55_API_URL || "https://core-manager.a55.tech";

try {
  const response = await fetch(`${base}/api/v1/bank/wallet/transfer/pix/`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
      "Idempotency-Key": "770e8400-e29b-41d4-a716-446655440002",
    },
    body: JSON.stringify({
      wallet_uuid: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      amount: 500.00,
      currency: "BRL",
      pix_key_type: "cpf",
      pix_key: "123.456.789-09",
      recipient_name: "张三",
      recipient_tax_id: "123.456.789-09",
      description: "供应商付款 #2048",
      reference_id: "PAY-2048",
    }),
  });

  if (!response.ok) throw new Error(`请求失败（HTTP ${response.status}）：${await response.text()}`);
  const transfer = await response.json();
  console.log(`转账：${transfer.transfer_uuid}——状态：${transfer.status}`);
} catch (error) {
  console.error("PIX 转账失败：", error.message);
}

---

错误响应示例

{
  "transfer_uuid": null,
  "status": "error",
  "message": [
    {
      "code": "INSUFFICIENT_BALANCE",
      "source": "wallet",
      "description": "Wallet balance is insufficient for this transfer amount"
    }
  ]
}

---

创建 PIX 收款 →通过二维码接收 PIX 付款。查询钱包 →在转账前查看钱包余额。Webhook 概述 →在转账完成时接收通知。