创建结账会话

POST/api/v1/bank/wallet/checkout/Bearer Token

---

请求头

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

请求体

字段	类型	必填	说明
wallet_uuid	string (UUID)	是	接收资金的钱包
merchant_id	string (UUID)	是	商户标识符
amount	number	是	收款总金额（例如 250.00）
currency	string	是	ISO 4217 货币代码
description	string	是	显示在结账页面的收款描述
redirect_url	string	是	支付完成后的重定向 URL
cancel_url	string	否	付款人取消时的重定向 URL
due_date	string	是	过期日期 YYYY-MM-DD
payer_email	string	否	在结账页面预填付款人邮箱
allowed_methods	array	否	限制支付方式（例如 ["credit_card", "pix"]）
max_installments	integer	否	允许的最大分期数（默认：钱包配置）
webhook_url	string	否	覆盖默认 webhook URL
reference_external_id	string	否	您的内部订单 ID
is_checkout	boolean	否	true（此 endpoint 的默认值）

---

响应字段

字段	类型	说明
checkout_uuid	string	唯一结账会话标识符
checkout_url	string	托管结账页面 URL——将付款人重定向至此
status	string	active——会话已准备好接受支付
amount	number	结账金额
currency	string	货币代码
expires_at	string	ISO 8601 会话过期时间
charge_uuid	string	付款人完成支付后创建

---

HTTP 状态码

状态码	说明
200	结账会话已创建
400	请求体无效或缺少必填字段
401	Bearer Token（持有者令牌）无效或已过期
403	该钱包权限不足
404	钱包或商户未找到
422	验证错误（无效货币、金额）
429	超出速率限制
500	服务器内部错误 - 请使用指数退避重试

---

代码示例

cURL

curl -s -X POST https://core-manager.a55.tech/api/v1/bank/wallet/checkout/ \
  -H "Authorization: Bearer $A55_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 990e8400-e29b-41d4-a716-446655440004" \
  -d '{
    "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "merchant_id": "11111111-1111-1111-1111-111111111111",
    "amount": 250.00,
    "currency": "BRL",
    "description": "高级计划——月度",
    "redirect_url": "https://your-app.com/payment/success",
    "cancel_url": "https://your-app.com/payment/cancel",
    "due_date": "2026-12-31",
    "payer_email": "zhangwei@example.com",
    "allowed_methods": ["credit_card", "pix"],
    "max_installments": 6,
    "webhook_url": "https://your-app.com/webhooks/a55",
    "reference_external_id": "ORDER-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/checkout/",
        json={
            "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
            "merchant_id": "11111111-1111-1111-1111-111111111111",
            "amount": 250.00,
            "currency": "BRL",
            "description": "高级计划——月度",
            "redirect_url": "https://your-app.com/payment/success",
            "cancel_url": "https://your-app.com/payment/cancel",
            "due_date": "2026-12-31",
            "payer_email": "zhangwei@example.com",
            "allowed_methods": ["credit_card", "pix"],
            "max_installments": 6,
            "webhook_url": "https://your-app.com/webhooks/a55",
            "reference_external_id": "ORDER-2048",
        },
        headers={
            "Authorization": f"Bearer {token}",
            "Content-Type": "application/json",
            "Idempotency-Key": "990e8400-e29b-41d4-a716-446655440004",
        },
    )
    response.raise_for_status()
    checkout = response.json()
    print(f"结账 URL：{checkout['checkout_url']}")
    print(f"会话：{checkout['checkout_uuid']}——过期时间：{checkout['expires_at']}")
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/checkout/`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
      "Idempotency-Key": "990e8400-e29b-41d4-a716-446655440004",
    },
    body: JSON.stringify({
      wallet_uuid: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      merchant_id: "11111111-1111-1111-1111-111111111111",
      amount: 250.00,
      currency: "BRL",
      description: "高级计划——月度",
      redirect_url: "https://your-app.com/payment/success",
      cancel_url: "https://your-app.com/payment/cancel",
      due_date: "2026-12-31",
      payer_email: "zhangwei@example.com",
      allowed_methods: ["credit_card", "pix"],
      max_installments: 6,
      webhook_url: "https://your-app.com/webhooks/a55",
      reference_external_id: "ORDER-2048",
    }),
  });

  if (!response.ok) throw new Error(`请求失败（HTTP ${response.status}）：${await response.text()}`);
  const checkout = await response.json();
  console.log(`结账 URL：${checkout.checkout_url}`);
  console.log(`会话：${checkout.checkout_uuid}——过期时间：${checkout.expires_at}`);
} catch (error) {
  console.error("结账创建失败：", error.message);
}

---

错误响应示例

{
  "status": "error",
  "message": [
    {
      "code": "INVALID_REDIRECT_URL",
      "source": "validation",
      "description": "redirect_url must be a valid HTTPS URL"
    }
  ]
}

---

支付链接 →创建可复用的支付链接用于分享。查询收款 →在结账完成后查看收款状态。Webhook 概述 →在结账完成支付时接收通知。