沙盒已开放联调,用测试卡,不动真钱Sandbox open: test cards, no real money

开发者指南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 pagePOST /v1/merchant/bind-sessions
买家确认支付Buyer confirms payment服务端锁定资金Hold funds from your serverPOST /v1/merchant/orders
你发货之后After you ship回传运单号Report the waybillPOST …/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.

API Key 只放在你的服务端,不要写进网页或 App。Keep the key on your server. Never put it in web pages or apps.

通用约定Conventions

保存买家的卡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
422status: failed卡被拒或额度不足,failure_reason 有原因。提示买家换卡,可用同一订单号重试。Card declined or over limit; see failure_reason. Ask for another card; retry with the same order number.
422binding_not_found卡不存在、不属于你,或这位买家还没保存卡。先走绑卡流程。No such card, not yours, or the buyer has none. Run card saving first.
422currency_not_supported目前只支持美元。USD only for now.
409merchant_order_no_conflict同一订单号用了不同金额,换一个订单号。Same order number with a different amount; use a new number.
502token_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 transit30%
CUSTOMS_CLEARED清关完成Customs cleared30%
DELIVERED签收Delivered40%

比例可以按商户约定调整。每一段会扣除约定的平台费,试点期为 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

  1. 联系我们开通沙盒商户,拿到 API Key 和测试卡。Contact us for a sandbox merchant, an API key and test cards.
  2. 用测试买家走一遍绑卡,服务端确认 status 为 bound。Save a card for a test buyer and confirm status is bound on your server.
  3. 锁一笔小额订单,例如 amount_minor = 100,查单确认为 captured。Hold a small order, say amount_minor = 100, and check it is captured.
  4. 回传一个运单号。沙盒里由 ATO 手动推进里程碑,你核对每段放款和推送事件。Report a waybill. In sandbox ATO advances the milestones by hand while you check each release and event.
  5. 取消一笔未发货的订单,确认额度已释放。Cancel an unshipped order and confirm the hold is released.

申请沙盒账号Request sandbox access