开发者指南Developer guide
三个服务端调用接入跨境 B2B 资金托管:保存买家的卡、结账时锁定资金、发货后回传运单。之后的物流跟踪、分段放款和状态推送都由 ATO 完成。Three server-side calls add cross-border B2B escrow to your site: save the buyer's card, hold funds at checkout, report the waybill after shipping. ATO handles tracking, staged release and status events from there.
接入概览Overview
| 时机When | 你做什么What you do | 接口Endpoint |
|---|---|---|
| 买家第一次付款Buyer's first payment | 创建绑卡会话,把买家跳到 ATO 托管的页面Open a session and redirect the buyer to the ATO-hosted page | POST /v1/merchant/bind-sessions |
| 买家确认支付Buyer confirms payment | 服务端锁定资金Hold funds from your server | POST /v1/merchant/orders |
| 你发货之后After you ship | 回传运单号Report the waybill | POST …/orders/{no}/shipment |
| 可选Optional | 接收签名推送,更新你的订单页Receive signed events to update your order page | 你提供的 https 地址Your https endpoint |
鉴权Authentication
所有服务端接口在请求头里带 ATO 为你开通的 API Key。Key 只能看到你自己商户的数据。Send the API key ATO issues to you on every server-side call. A key only sees your own merchant's data.
Authorization: Bearer <api_key>
没带 Key 返回 401;用别家的 Key 查你的订单返回 404,不会泄露订单是否存在。买家浏览器访问的绑卡页不需要 Key,一次性的会话编号就是凭证。No key returns 401. Another merchant's key returns 404 for your orders, so existence is never revealed. The card page the buyer opens needs no key; the one-time session id is the credential.
通用约定Conventions
- 金额一律用最小货币单位的整数,字段名
amount_minor。美元即美分,125000表示 USD 1,250.00。Amounts are integers in minor units, fieldamount_minor. For USD that is cents:125000means USD 1,250.00. - 目前只支持
currency = "USD",其他币种返回 422currency_not_supported。Onlycurrency = "USD"for now; others return 422currency_not_supported. - 你的订单号
merchant_order_no是幂等键。同号重发返回同一结果并带idempotent_replay: true;同号不同金额返回 409。Yourmerchant_order_nois the idempotency key. Repeating it returns the same result withidempotent_replay: true; the same number with a different amount returns 409. - 错误体统一为
{"detail": {"error": "<code>", ...}}。Errors look like{"detail": {"error": "<code>", ...}}. - 时间为 ISO-8601 UTC,以
Z结尾。Times are ISO-8601 UTC ending inZ.
保存买家的卡Save a buyer's card
每个买家只做一次。卡号和 CVV 由收单机构的组件处理,不经过你,也不经过 ATO 的服务器。Once per buyer. The acquirer's component handles the card number and CVV; they never reach you or ATO's servers.
1. 创建会话1. Open a session
POST /v1/merchant/bind-sessions
{
"buyer_ref": "buyer-10086",
"return_url": "https://shop.example.com/account/cards",
"buyer_email": "finance@buyer.example"
}
| 字段Field | 必填Required | 说明Notes |
|---|---|---|
buyer_ref | 是Yes | 你这边的买家标识。之后下单传同一个值,就会用这位买家的卡。Your id for the buyer. Pass the same value when ordering to use this buyer's card. |
return_url | 是Yes | 绑卡结束后跳回的页面,http(s) 绝对地址。Where the buyer returns afterwards; an absolute http(s) URL. |
buyer_email | 建议Recommended | 发卡行身份验证邮件的收件人。Recipient for the issuer's verification email. |
返回 201,其中 bind_url 是买家要打开的页面。会话 24 小时有效,可以通过邮件发给买家;买家打开页面后需在 30 分钟内完成填卡。Returns 201 with bind_url, the page for the buyer. The session lasts 24 hours, so you can email it; once opened, the card form must be completed within 30 minutes.
2. 跳转与回跳2. Redirect and return
把买家浏览器重定向到 bind_url。无论成功、失败还是取消,都会跳回 return_url 并带上参数:Redirect the buyer's browser to bind_url. Success, failure or cancellation all return to return_url with:
?ato_bind_session=bs_Qm4…&ato_status=success&buyer_ref=buyer-10086&binding_id=5c1e…
3. 服务端确认3. Confirm on your server
GET /v1/merchant/bind-sessions/{session_id}
只有 status 为 bound 且 binding_id 有值,才算绑卡成功。不要只信回跳参数。返回中的 card 字段带卡组织和后四位,可用于展示。Treat the card as saved only when status is bound and binding_id is set. Do not rely on the redirect alone. The card field carries brand and last four digits for display.
锁定资金Hold funds
买家点"确认支付"时调用。成功后即可给买家显示支付成功,然后照常采购。这一步只是把钱锁进托管,不购买任何商品。Call when the buyer confirms payment. On success, show the payment as done and source as usual. This only holds the money; it buys nothing.
POST /v1/merchant/orders
{
"merchant_order_no": "SO20261110-000123",
"amount_minor": 125000,
"currency": "USD",
"buyer_ref": "buyer-10086",
"items": [{"sku": "SKU-1", "name": "Servo driver 48V/10A", "qty": 2, "unit_price_minor": 62500}],
"shipping_address": {"name": "Ada Wong", "phone": "+852 9000 0000",
"address1": "1 Queen's Road Central", "city": "Central", "state": "HK",
"zip": "999077", "country": "HK"}
}
| 字段Field | 必填Required | 说明Notes |
|---|---|---|
merchant_order_no | 是Yes | 你的订单号,不超过 64 个字符,也是幂等键。Your order number, up to 64 characters; also the idempotency key. |
amount_minor | 是Yes | 要锁定的总额,含货款和运费,大于 0。Total to hold, goods plus shipping; greater than 0. |
buyer_ref / binding_id | 二选一One of | 传 binding_id 指定一张卡;只传 buyer_ref 时用这位买家最近保存的卡。Pass binding_id for a specific card, or buyer_ref to use that buyer's latest card. |
items / shipping_address | 建议Recommended | 只用于记录和争议举证,不参与计价。Kept as a record and dispute evidence; not used for pricing. |
成功返回 201,status 为 captured,并带 credit_lock_id,请保存在你的订单上。Success returns 201 with status captured and a credit_lock_id to store on your order.
| HTTP | 错误Error | 含义与处理Meaning and what to do |
|---|---|---|
| 422 | status: failed | 卡被拒或额度不足,failure_reason 有原因。提示买家换卡,可用同一订单号重试。Card declined or over limit; see failure_reason. Ask for another card; retry with the same order number. |
| 422 | binding_not_found | 卡不存在、不属于你,或这位买家还没保存卡。先走绑卡流程。No such card, not yours, or the buyer has none. Run card saving first. |
| 422 | currency_not_supported | 目前只支持美元。USD only for now. |
| 409 | merchant_order_no_conflict | 同一订单号用了不同金额,换一个订单号。Same order number with a different amount; use a new number. |
| 502 | token_mint_failed | 卡组织服务暂时异常,稍后重试。Card network service unavailable; retry later. |
回传运单Report the waybill
POST /v1/merchant/orders/{merchant_order_no}/shipment
{"tracking_no": "LP00123456789HK", "carrier_code": "17track"}
carrier_code 默认为 17track,即自动识别承运商。同一订单可以回传多个运单,同一运单号重复回传不会重复处理。返回的 tracking.registered 为 false 时,表示没能自动订阅物流,ATO 会人工跟进,你这边不需要处理。已取消或已结清的订单返回 409 order_not_shippable。carrier_code defaults to 17track, which detects the carrier automatically. One order can have several waybills; repeating a waybill number is harmless. If tracking.registered is false, tracking could not be subscribed automatically and ATO follows up; nothing to do on your side. Cancelled or settled orders return 409 order_not_shippable.
查单与对账Status and reconciliation
GET /v1/merchant/orders/{merchant_order_no}
status | 含义Meaning |
|---|---|
captured | 已锁定,未发货Held, not shipped |
shipped | 已回传运单Waybill reported |
partial_released | 已放出部分款项Part released |
released | 全部放完Fully released |
cancelled · disputed · refunded · expired | 已取消、争议中、已退款、已过期Cancelled, in dispute, refunded, expired |
tranches 列出每一段放款的里程碑、比例、金额和时间;disbursements 是收单机构的账本回执,表示该笔已记入划款,实际到账以银行流水为准。tranches lists each release with milestone, ratio, amount and time. disbursements are the acquirer's ledger receipts: the release is booked for payout; actual arrival follows your bank statement.
GET /v1/merchant/orders?since=…&until=…&status=…&limit=…
按创建时间倒序列出你的订单,用于每日对账,limit 最大 500。Your orders, newest first, for daily reconciliation; limit up to 500.
取消与争议Cancel and dispute
POST /v1/merchant/orders/{no}/cancel
只能在发货前取消,全额退回买家卡。已发货的订单返回 409 already_shipped,请改用争议。Before shipping only; the full amount returns to the buyer's card. Shipped orders return 409 already_shipped; open a dispute instead.
POST /v1/merchant/orders/{no}/dispute
{"reason": "Buyer reports wrong model", "evidence_urls": ["https://…/photo.jpg"]}
发货后买家投诉时调用。尚未放出的款项立即冻结,由 ATO 审核:同意则退回未放部分,已放部分不回追;驳回则恢复放款。未发货返回 409 not_shipped,争议未结时重复调用返回同一结果。Use when a buyer complains after shipping. The unreleased part is frozen at once and ATO reviews: if approved it is refunded and released parts are not clawed back; if rejected, releases resume. Unshipped orders return 409 not_shipped; repeating while open returns the same result.
放款规则Release schedule
| 里程碑Milestone | 触发Trigger | 默认比例Default |
|---|---|---|
INTL_TRANSIT | 承运商显示离境或国际在途Carrier shows departure or international transit | 30% |
CUSTOMS_CLEARED | 清关完成Customs cleared | 30% |
DELIVERED | 签收Delivered | 40% |
比例可以按商户约定调整。每一段会扣除约定的平台费,试点期为 0。The split can be agreed per merchant. Each release deducts the agreed platform fee, which is zero during the pilot.
状态推送Webhooks
提供一个 https 地址和一个 32 位以上的随机密钥,ATO 会把以下事件推送过去:Give us an https endpoint and a random secret of 32+ characters, and ATO will post these events:
| 事件Event | 时机When |
|---|---|
order.captured | 资金已锁定Funds held |
order.shipped | 运单已回传Waybill reported |
logistics.milestone | 到达放款里程碑Release milestone reached |
tranche.released | 一段款放出A tranche released |
order.cancelled | 已取消Cancelled |
dispute.opened · dispute.resolved | 争议开启、审核结果Dispute opened, decision made |
X-ATO-Event: tranche.released
X-ATO-Delivery: evt_8f2a… # dedupe on this
X-ATO-Signature: t=1762916044,v1=<hex>
{"id": "evt_8f2a…", "type": "tranche.released", "created_at": "2026-11-12T03:10:44Z",
"merchant_order_no": "SO20261110-000123", "credit_lock_id": "7a3f…", "data": {…}}
验签:v1 = HMAC-SHA256(secret, "<t>." + 原始请求体),并拒绝与当前时间相差超过 300 秒的请求。返回 2xx 视为送达,否则会重试,重试时请求体和签名保持不变。Verify v1 = HMAC-SHA256(secret, "<t>." + raw body) and reject anything more than 300 seconds old. A 2xx counts as delivered; otherwise we retry with the same body and signature.
import hmac, hashlib, time
def verify(secret: str, header: str, raw_body: bytes) -> bool:
kv = dict(p.split("=", 1) for p in header.split(","))
if abs(time.time() - int(kv["t"])) > 300:
return False
mac = hmac.new(secret.encode(), f"{kv['t']}.".encode() + raw_body,
hashlib.sha256).hexdigest()
return hmac.compare_digest(mac, kv["v1"])
沙盒联调Sandbox
- 联系我们开通沙盒商户,拿到 API Key 和测试卡。Contact us for a sandbox merchant, an API key and test cards.
- 用测试买家走一遍绑卡,服务端确认
status为bound。Save a card for a test buyer and confirmstatusisboundon your server. - 锁一笔小额订单,例如
amount_minor = 100,查单确认为captured。Hold a small order, sayamount_minor = 100, and check it iscaptured. - 回传一个运单号。沙盒里由 ATO 手动推进里程碑,你核对每段放款和推送事件。Report a waybill. In sandbox ATO advances the milestones by hand while you check each release and event.
- 取消一笔未发货的订单,确认额度已释放。Cancel an unshipped order and confirm the hold is released.