常见集成错误
Quick Reference
1. 在 sandbox（沙箱环境）中使用生产凭证
症状： 向 sandbox.api.a55.tech 发送的所有请求均返回 401 Unauthorized。
修复： 沙箱和生产环境使用不同的 Cognito 池。请使用沙箱的 client_id、client_secret 配合沙箱认证 URL，生产凭证配合生产认证 URL。
2. 未处理 3DS（3D Secure 验证）重定向
症状： 使用已注册 3DS 的卡片进行的收款一直停留在 awaiting_3ds 状态。
修复： 当收款响应中包含 redirect_url 时，将持卡人重定向到该 URL。身份验证完成后，用户会返回到您的 callback_url，此时您需要轮询收款状态。
3. 硬编码 API（应用程序编程接口）令牌
症状： 令牌在 1 小时后过期，所有请求均返回 401 错误。
修复： 切勿硬编码令牌。实现一个令牌管理器，在过期前调用 OAuth（开放授权）2 端点：
import time
class TokenManager:
def __init__(self):
self._token = None
self._expires_at = 0
def get_token(self):
if time.time() > self._expires_at - 60:
self._refresh()
return self._token
def _refresh(self):
# 调用 OAuth2 令牌端点
self._token = response["access_token"]
self._expires_at = time.time() + response["expires_in"]
4. 未验证 webhook（网络钩子）签名
症状： 您的系统处理了伪造的 webhook 载荷，导致订单状态更新错误。
修复： 在处理之前始终验证 HMAC（基于哈希的消息认证码）-SHA256 签名：
import hmac
import hashlib
def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
expected = hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature)
5. 重试时缺少幂等键
症状： 由于超时触发了重试但未使用相同的 Idempotency-Key，客户被重复扣款。
修复： 每个业务操作只生成一次 UUID（通用唯一标识符）v4，并在每次尝试中发送：
import uuid
idempotency_key = str(uuid.uuid4()) # 仅生成一次
# 重试时使用相同的密钥
headers = {"Idempotency-Key": idempotency_key}
6. 金额格式错误
症状： 422 Unprocessable Entity，amount 字段验证失败。
修复： 金额格式取决于该货币的小数位数；须为符合规则的字符串（不能省略小数位或使用错误的小数位数）。
| 货币 | 小数位 | 正确示例 |
|---|---|---|
| BRL、MXN、USD、EUR、PEN、ARS | 2 | 150.00 |
| CLP、COP | 0 | 50000 |
注意： CLP 与 COP 为零小数货币；若传入小数，后端会截断小数部分。
7. 缺少付款人必填字段
症状： 422 错误，列出缺少的字段如 payer.document 或 payer.email。
修复： 每笔收款至少需要以下信息：
{
"payer": {
"name": "张伟",
"email": "zhangwei@example.com",
"document": "12345678909",
"document_type": "CPF"
}
}
证件要求因国家而异（巴西使用 CPF，墨西哥使用 RFC）。
8. 未实现指数退避重试
症状： 系统在收到 500 错误后持续发送请求，被限速后使故障更加严重。
修复： 实现带抖动的指数退避：
import time
import random
for attempt in range(4):
response = make_request()
if response.status_code < 500:
break
delay = (2 ** attempt) + random.uniform(0, 1)
time.sleep(delay)
9. 忽略速率限制
症状： 在流量高峰期突然收到 429 Too Many Requests 响应。
修复： 读取速率限制头部（X-RateLimit-Remaining、X-RateLimit-Reset）并主动降速。参见速率限制指南。
10. 创建收款后不检查状态
症状： 创建收款后立即将订单标记为已付款，但收款实际处于 pending 或 declined 状态。
修复： 创建收款后，检查响应中的 status 字段。对于异步支付方式（PIX、Boleto），设置 webhook 来接收状态更新——不要假定收款已确认。
11. 创建收款时缺少 webhook_url
症状： 没有收到 webhook 通知，即使您的端点正常工作。
修复： 在创建收款的请求体中包含 webhook_url，或在商户设置中配置默认 webhook URL。
12. 国家与货币不匹配
症状： 422 错误或意外的汇率转换费用。
修复： 为每个国家使用正确的货币，并按该货币的小数位数格式化 amount，同时提供该国要求的证件类型：
| 国家 | 货币 | 小数位 | 证件类型 | 金额示例 |
|---|---|---|---|---|
| 巴西 | BRL | 2 | CPF / CNPJ | 150.00 |
| 墨西哥 | MXN | 2 | RFC / CURP | 2500.00 |
| 智利 | CLP | 0 | RUT | 50000 |
| 哥伦比亚 | COP | 0 | CC (Cédula) | 200000 |
| 秘鲁 | PEN | 2 | DNI | 350.00 |
| 阿根廷 | ARS | 2 | DNI / CUIT | 85000.00 |
13. 未正确处理部分扣款
症状： 仅发了部分货物，却全额扣款。
修复： 当扣款金额小于授权金额时，需明确设置扣款金额：
{
"amount": "75.00"
}
剩余授权金额将自动释放。
14. 代码中缺少错误处理
症状： 当 API 返回非预期响应时，未处理的异常导致应用崩溃。
修复： 将每个 API 调用包装在 try/catch 中，并处理所有可能的 HTTP 状态码。记录每个失败请求的 request_id。
15. 未测试所有卡片拒绝场景
症状： 当卡片被拒绝时，应用崩溃或显示通用错误信息。
修复： 使用所有拒绝测试卡进行测试，并验证您的界面显示了合适的信息：
| 测试卡 | 场景 |
|---|---|
4000 0000 0000 0002 | 卡片被拒绝 |
4000 0000 0000 0069 | 处理错误 |
4000 0000 0000 0119 | 余额不足 |