查询收款

Quick Reference

What通过 UUID 查询单笔收款

Why实时检查支付状态、验证金额和对账交易

Reading Time5 分钟

Difficulty初级

Prerequisites身份验证 → 创建收款

GET/api/v1/bank/wallet/charge/Bearer Token查询收款详情

为什么要轮询收款状态

没有查询收款	使用查询收款
创建收款后无法了解后续情况	随时查看确切状态
对账依赖人工检查	自动对账将您的记录与 A55 匹配
客服无法回答"我的支付在哪里？"	通过收款 UUID（通用唯一标识符）为客服即时查询
丢失的 Webhook（网络钩子）让您无从知晓	当 Webhook 失败或延迟到达时，轮询填补空白
无状态变更的审计追踪	`updated_at` 跟踪每次状态变更的时间戳

轮询模式

身份验证

需要 Bearer 令牌。参见身份验证。

查询参数

两个参数在查询字符串中均为必填：

字段	类型	必填	说明
`charge_uuid`	string (UUID)	是	要查询的收款唯一标识符
`wallet_uuid`	string (UUID)	是	拥有该收款的钱包

无请求体

这是一个 GET 端点。将两个 UUID 作为查询参数传递，而不是放在请求体中。

代码示例

cURL
Python
JavaScript

curl -s -X GET "https://core-manager.a55.tech/api/v1/bank/wallet/charge/?charge_uuid=51dcca6e-7310-4b73-a94c-90835408f2ff&wallet_uuid=f47ac10b-58cc-4372-a567-0e02b2c3d479" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"

import requests
import os

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

response = requests.get(
    f"{base}/api/v1/bank/wallet/charge/",
    params={
        "charge_uuid": "51dcca6e-7310-4b73-a94c-90835408f2ff",
        "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    },
    headers={"Authorization": f"Bearer {token}"},
)

charge = response.json()
print(f"状态：{charge['status']} | 金额：{charge['currency']} {charge['local_currency']}")

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

const params = new URLSearchParams({
  charge_uuid: "51dcca6e-7310-4b73-a94c-90835408f2ff",
  wallet_uuid: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
});

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

console.log(`状态：${charge.status} | 金额：${charge.currency} ${charge.local_currency}`);

指数退避实用轮询

Python
JavaScript

import requests, os, time

token = os.environ["A55_API_TOKEN"]
base = os.environ.get("A55_API_BASE_URL", "https://core-manager.a55.tech")
TERMINAL = {"paid", "confirmed", "error", "canceled", "refunded"}

def poll_charge(charge_uuid, wallet_uuid, max_attempts=10):
    delay = 2
    for attempt in range(max_attempts):
        resp = requests.get(
            f"{base}/api/v1/bank/wallet/charge/",
            params={"charge_uuid": charge_uuid, "wallet_uuid": wallet_uuid},
            headers={"Authorization": f"Bearer {token}"},
        )
        charge = resp.json()
        status = charge["status"]
        print(f"[{attempt+1}/{max_attempts}] 状态：{status}")

        if status in TERMINAL:
            return charge

        time.sleep(delay)
        delay = min(delay * 2, 60)

    raise TimeoutError("收款未达到终态")

const TERMINAL = new Set(["paid", "confirmed", "error", "canceled", "refunded"]);

async function pollCharge(chargeUuid, walletUuid, maxAttempts = 10) {
  let delay = 2000;
  for (let i = 0; i < maxAttempts; i++) {
    const params = new URLSearchParams({ charge_uuid: chargeUuid, wallet_uuid: walletUuid });
    const charge = await fetch(`${base}/api/v1/bank/wallet/charge/?${params}`, {
      headers: { Authorization: `Bearer ${token}` },
    }).then((r) => r.json());

    console.log(`[${i + 1}/${maxAttempts}] 状态：${charge.status}`);
    if (TERMINAL.has(charge.status)) return charge;

    await new Promise((r) => setTimeout(r, delay));
    delay = Math.min(delay * 2, 60000);
  }
  throw new Error("收款未达到终态");
}

响应字段

字段	类型	说明
`charge_uuid`	string	收款唯一标识符
`wallet_uuid`	string	拥有此收款的钱包
`status`	string	当前收款状态（见下表）
`type_charge`	string	支付方式：`credit_card`、`debit_card`、`pix`、`boleto`、`spei`、`oxxo`、`applepay`、`googlepay`、`e_wallet`
`amount`	number	原始币种的收款总金额
`local_currency`	number	钱包结算币种的金额
`currency`	string	ISO 4217 货币代码
`usd_currency`	number	等值美元金额
`eur_currency`	number	等值欧元金额
`installment_count`	integer	分期数
`installments`	array	每期分期明细（见下方）
`created_at`	string	ISO 8601 创建时间戳
`updated_at`	string	ISO 8601 最后更新时间戳

收款状态

状态	是否终态？	说明
`issued`	否	收款已创建，等待付款人操作（PIX 二维码、Boleto、结账）
`pending`	否	处理中——等待收单机构或 3DS 响应
`confirmed`	是	支付已授权并成功捕获
`paid`	是	资金已收到并确认
`error`	是	支付失败——详见 `message` 数组
`canceled`	是	收款在完成前被取消
`refunded`	是	收款已退款（全额或部分）

分期对象

字段	类型	说明
`installment_number`	integer	分期序号（从 1 开始）
`local_currency`	number	结算币种的分期金额
`currency`	string	ISO 4217 货币代码
`usd_currency`	number	美元分期金额
`eur_currency`	number	欧元分期金额
`due_date`	string	分期到期日
`status`	string	分期级别状态

完整响应示例

{
  "charge_uuid": "51dcca6e-7310-4b73-a94c-90835408f2ff",
  "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "confirmed",
  "type_charge": "credit_card",
  "amount": 450.00,
  "local_currency": 450.00,
  "currency": "BRL",
  "usd_currency": 80.73,
  "eur_currency": 70.78,
  "installment_count": 3,
  "installments": [
    {
      "installment_number": 1,
      "local_currency": 150.00,
      "currency": "BRL",
      "usd_currency": 26.91,
      "eur_currency": 23.59,
      "due_date": "2026-03-20",
      "status": "confirmed"
    },
    {
      "installment_number": 2,
      "local_currency": 150.00,
      "currency": "BRL",
      "usd_currency": 26.91,
      "eur_currency": 23.59,
      "due_date": "2026-04-20",
      "status": "confirmed"
    },
    {
      "installment_number": 3,
      "local_currency": 150.00,
      "currency": "BRL",
      "usd_currency": 26.91,
      "eur_currency": 23.60,
      "due_date": "2026-05-20",
      "status": "confirmed"
    }
  ],
  "created_at": "2026-03-20T14:30:00-03:00",
  "updated_at": "2026-03-20T14:30:05-03:00"
}

错误响应

状态码	代码	说明	解决方式
400	`validation_error`	缺少 `charge_uuid` 或 `wallet_uuid`	两个查询参数都是必填的
401	`unauthorized`	无效或过期的 Bearer 令牌	通过 Cognito 刷新您的访问令牌
404	`errors.wallet.not_found`	钱包 UUID 不存在	验证 `wallet_uuid` 是否正确
404	`CHARGE_NOT_FOUND`	在此钱包中未找到收款	验证两个 UUID 是否与原始收款匹配
429	`rate_limit_exceeded`	请求过于频繁	等待并在 `Retry-After` 头值之后重试

不要过度轮询

每秒轮询超过一次会触发频率限制。对于实时需求，请使用Webhook，将轮询保留用于对账和客服查询。

两个 UUID 都是必填的

仅传递 charge_uuid 而没有 wallet_uuid 将返回 400 错误。API 强制钱包级别的作用域以确保安全——您只能检索属于您钱包的收款。

捕获收款 →捕获之前授权的支付。退款 →对已捕获的收款进行退款——全额或部分。Webhook 概述 →接收实时状态更新，而非轮询。

Quick Reference

为什么要轮询收款状态​

轮询模式​

身份验证​

查询参数​

代码示例​

指数退避实用轮询​

响应字段​

收款状态​

分期对象​

完整响应示例​

错误响应​