入门

English

重要说明

现有对接自身无法察觉的 HansaPay 行为。接入前请先阅读。

本文档中的请求与响应格式没有变化,现有对接无需修改代码即可继续使用。以下行为是现有对接自身无法察觉的:

  • 金额可能向下取整到价位。 Apple Pay、Google Pay 及部分卡通道只按固定价位收款。HansaPay 会把金额向下取整到最接近的价位(最多 5%):trans_amount 为实收金额,requested_amount 为你传入的金额。见 钱包支付直连。请按 order_no / merchant_order_no 对账,不要按金额对账。
  • 通知返回实收的美元金额。 对于其他币种的订单,API 响应返回你传入的币种与金额,而 payment.updated 与 refund.updated 通知返回实收或实退的美元金额。
  • 其他币种的支付含汇率加点。 以美元以外币种发起的银行卡或钱包支付,按市场汇率加汇率加点(默认 1.5%,另有约定的除外)以美元扣款。你的余额入账与手续费均按你的价格以市场汇率换算后的金额计算。加点不属于你,因此 payment.updated 中的美元金额会高于余额在扣除手续费前的入账金额。退款或拒付只扣减属于你的部分。
  • 支持的币种。 支付与支付链接可使用以下币种定价:USD, EUR, GBP, CAD, AUD, NZD, CHF, JPY, HKD, SGD, PLN, SEK, NOK, AED, SAR, OMR。其他币种会以 code=422 拒绝,错误信息会列出支持的币种。以美元以外币种定价的支付按当日市场汇率换算后以美元扣款。若暂时没有可用的汇率,支付会以 code=422 拒绝,信息为 "exchange rate is temporarily unavailable":请稍后重试或改用美元。
  • 拒付不发通知。 拒付一经记录即从你的余额中冻结:属于你的金额部分与拒付手续费将无法提现,并在其结算日从冻结中扣除。若余额不足,余额会变为负数,由你之后的入账优先抵扣。拒付仅在商户后台展示。不发送通知,支付状态保持 SUCCESS。
  • 卡类退款为全额退款且需审核。 卡、Apple Pay 与 Google Pay 支付只能退款一次,且须全额。退款初始为 PENDING,审核后才完成。见 创建退款。
  • 已停用的账户不能收款。 /payments/create 与 /payments/checkout 返回 code=1001。查询、退款与结算不受影响。
  • 下单有频率限制。 每个商户账户通过 /payments/create 与 /payments/checkout 合计每分钟最多创建 600 笔付款(另有约定的除外)。超出时请求以 HTTP 429 和 code=4001(tooManyRequests)拒绝,且不会创建订单:请稍候以相同的 merchant_order_no 重试。查询、退款与代付不计入。
  • PAYPAL 与 PIX 目前不可用。 它们能通过参数校验,随后以 code=3003 拒绝。代付目前仅支持 CASH_APP:在您的账户开通代付后,以 USD 付至 Cash App $cashtag。其他代付方式返回 code=5007。见第 8 节。
  • 通知必须以 success 应答。 其他任何应答都会重试,约 90 分钟内最多 9 次。同一通知可能到达多次。见 商户回调响应要求。
  • 结算按美国工作日计算。 T+N 从订单创建当天起按周一至周五计算,不含元旦、阵亡将士纪念日、独立日、劳动节、感恩节和圣诞节。部分支付通道仅在特定工作日放款:经这类通道的付款在其 T+N 日期当天或之后的第一个放款日结算(例如随后的周五)。每笔订单的结算日期会随订单一起显示。