支付接口

创建支付订单（统一入口）#

说明：

• /api/v1/payments/create 是统一支付下单入口
• HansaPay 系统会根据 payment_method 分发请求
• 支持的 payment_method：
  • CARD
  • CASH_APP
  • PAYPAL（目前不可用）
  • APPLE_PAY
  • GOOGLE_PAY
  • PIX（目前不可用）

通用字段：

卡支付直连#

适用：

• payment_method=CARD

附加字段：

卡支付请求示例：

{
  "payment_method": "CARD",
  "merchant_order_no": "M202406240001",
  "trans_amount": {
    "currency": "USD",
    "value": "99.99"
  },
  "notify_url": "https://merchant.example.com/callback/payment",
  "return_url": "https://merchant.example.com/pay/success",
  "trade_info": {
    "goods_name": "VIP Membership",
    "description": "Monthly subscription"
  },
  "metadata": "biz=member&uid=10001",
  "card": {
    "card_number": "4111111111111111",
    "cardholder_name": "JOHN DOE",
    "exp_month": 12,
    "exp_year": 2028,
    "cvc": "123"
  },
  "billing_address": {
    "country": "US",
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]",
    "phone": "15551234567",
    "state": "CA",
    "city": "San Francisco",
    "address": "Market Street",
    "street_number": "1355",
    "postal_code": "94103"
  },
  "device_ip": "203.0.113.10",
  "client_ip": "203.0.113.10"
}

成功 data#

说明：

• 即使金额已取整到价位，本响应也不含 requested_amount；请使用查单或通知获取
• 若卡被拒，响应为 code=422、Payment request failed|paymentFailed，不含 order_no；随后会发送 status=FAILED 的 payment.updated 通知
• 卡号、CVC 或有效期无效时返回 System busy, please try again later|systemBusy

钱包支付直连#

适用：

• payment_method=CASH_APP
• payment_method=APPLE_PAY
• payment_method=GOOGLE_PAY
• payment_method=PAYPAL 与 payment_method=PIX 目前不可用（code=3003）

APPLE_PAY / GOOGLE_PAY 为托管钱包页：将付款人跳转到 pay_url，钱包面板在该页面呈现并完成支付。这两种方式下 HansaPay 不采集卡信息。付款人字段一般可选，除非路由到的通道有额外要求（错误信息会指明缺失字段）。

钱包金额档位。 钱包上游只按固定价位收款（USD 4.99、5.99、6.99、7.99、8.99、9.90、9.99、10.99、11.99、12.99、13.99、14.99、15.99、17.99、19.80、19.99、24.99、29.99、30.99、39.99、49.50、49.99、59.99、89.99、99.99、124.99、129.99、149.99、159.99、199.99、249.99、299.99、399.99、499.99）。创建 APPLE_PAY / GOOGLE_PAY 订单（或在收银台通过快捷按钮把卡订单切换为钱包）时，HansaPay 会把金额向下取整到最接近的档位：请求 USD 11.00 时实收、入账与回传均为 USD 10.99。所有响应、查单与通知中的 trans_amount 为实收金额，原请求金额另以 requested_amount 返回（结构同 trans_amount，未取整时省略）。手续费按实收金额计算。低于 USD 4.99、高于 USD 499.99、或比最近的较低档位高出 5% 以上的金额不支持钱包支付：POST/api/v1/payments/create 返回 code=422（notSupported），收银台则不展示钱包按钮，付款人改用卡支付。钱包订单请按 order_no / merchant_order_no 对账，不要按金额精确匹配。

部分通道的卡金额档位。 部分卡通道只接受固定价位（USD 9.99、10.99、11.99、12.99、13.99、14.99、17.99、19.99、24.99、29.99、30.99、39.99、49.99、59.99、99.99、124.99、129.99、149.99、199.99、249.99、299.99、399.99、499.99）。CARD 订单（直连或托管收银台）路由到此类通道时，HansaPay 会在创建订单时把金额向下取整到最接近的档位，同样以 5% 为限：请求 USD 12.50 时实收、入账与回传均为 USD 11.99，requested_amount 为 USD 12.50。没有档位可匹配的金额（低于 USD 9.99、高于 USD 499.99、或比最近的较低档位高出 5% 以上）会路由到其他卡通道；只有当没有任何通道能接收时，POST/api/v1/payments/create 才返回金额错误（code=2006）。每个卡档位同时也是钱包档位，因此通过快捷按钮切换为钱包的收银台订单不会被二次取整。与钱包相同，请按 order_no / merchant_order_no 对账，不要按金额精确匹配。

附加字段：

部分通道要求额外的付款人字段；缺失或格式非法会在订单创建前被拒绝，错误信息中会指出具体字段，如 payer.document。

钱包支付请求示例：

{
  "payment_method": "CASH_APP",
  "merchant_order_no": "M202406240003",
  "trans_amount": {
    "currency": "USD",
    "value": "49.99"
  },
  "notify_url": "https://merchant.example.com/callback/payment",
  "return_url": "https://merchant.example.com/pay/success",
  "trade_info": {
    "goods_name": "Gift Card",
    "description": "Cash App checkout"
  },
  "metadata": "channel=cashapp",
  "payer": {
    "email": "[email protected]",
    "payer_id": "PAYER123456"
  },
  "client_ip": "1.1.1.1"
}

说明：

• 钱包支付创建成功后，商户前端应直接使用 pay_url 跳转用户
• 当 next_action=REDIRECT 时，表示应立即跳转到 pay_url
• 钱包支付不需要再走收银台流程
• 若返回 code=2006，表示本次代收金额不满足当前可用通道限额

成功 data#

完整成功响应示例#

{
  "code": 0,
  "msg": "success",
  "data": {
    "payment_method": "CASH_APP",
    "order_no": "O202406240003",
    "merchant_order_no": "M202406240003",
    "status": "PENDING",
    "trans_amount": {
      "currency": "USD",
      "value": "49.99"
    },
    "next_action": "REDIRECT",
    "pay_url": "https://wallet.example.com/redirect/pay_abc123",
    "created_at": "2026-06-24T10:03:00+08:00"
  }
}

收银台下单#

说明：

• 收银台模式创建 payment_method=CARD 订单并返回托管收银台页面
• 收银台模式同样接受钱包方式（APPLE_PAY、GOOGLE_PAY、CASH_APP），此时 checkout_url 即钱包支付页面
• 收到 checkout_url 后请立即保存。它 30 分钟后失效，查单不返回该链接，且以相同 merchant_order_no 重复请求会被视为重复而拒绝。链接过期仍未支付的订单保持 CHECKOUT_REQUIRED
• 若商户同时开通了 Apple Pay / Google Pay 通道，收银台页面会在卡表单上方展示快捷钱包按钮。付款人选择钱包后，同一笔订单（order_no、merchant_order_no 不变）会切换为 payment_method=APPLE_PAY / GOOGLE_PAY 并跳转到钱包页面，后续查单与通知均返回钱包方式及其费率快照。若金额不在钱包档位上，切换时会向下取整（见上文钱包金额档位）；美元订单的页面会在付款人点击前提示钱包实收金额，切换后 requested_amount 保留原金额。
• 不经托管页面的服务端钱包下单请使用 POST/api/v1/payments/create
• 若返回 code=2006，表示代收金额不满足当前可用通道限额

与直连下单的差异#

• 不传 card
• 不传 billing_address
• 不传 device_ip
• 由用户在收银台页面自行完成支付信息输入

请求核心字段#

成功 data#

说明：

• CARD 时 status 与 next_action 均为 CHECKOUT_REQUIRED。钱包方式时 status 为 PENDING，next_action 为 REDIRECT
• 若付款人在收银台页面使用了快捷钱包按钮，后续查单与通知中的 payment_method 将为 APPLE_PAY / GOOGLE_PAY。此时 trans_amount 可能低于原请求金额（钱包档位），原请求金额以 requested_amount 返回。卡订单路由到有卡金额档位的通道时同理（见部分通道的卡金额档位）。

完整成功响应示例#

{
  "code": 0,
  "msg": "success",
  "data": {
    "payment_method": "CARD",
    "order_no": "O202406240002",
    "merchant_order_no": "M202406240002",
    "status": "CHECKOUT_REQUIRED",
    "trans_amount": {
      "currency": "USD",
      "value": "49.99"
    },
    "next_action": "CHECKOUT_REQUIRED",
    "token": "5c4f0f53-c0e9-4d11-8a2b-0f3e6a1d9b27",
    "checkout_url": "https://cashier.example.com/pay/5c4f0f53-c0e9-4d11-8a2b-0f3e6a1d9b27",
    "created_at": "2026-06-24T10:05:00+08:00"
  }
}

查询支付订单#

请求字段#

二选一：

成功 data#

订单状态取值：PENDING、CHECKOUT_REQUIRED、3DS_VERIFICATION_REQUIRED、PROCESSING、SUCCESS、FAILED、PARTIAL_REFUNDED、REFUNDED。

说明：

• 查询仍在处理中的订单时，会同时向上游获取最新状态
• 极少数情况下，已报 FAILED 的卡支付之后被确认已付款并变为 SUCCESS，并会发送新的通知

完整成功响应示例#

{
  "code": 0,
  "msg": "success",
  "data": {
    "payment_method": "CARD",
    "order_no": "O202406240001",
    "merchant_order_no": "M202406240001",
    "status": "SUCCESS",
    "trans_amount": {
      "currency": "USD",
      "value": "99.99"
    },
    "paid_at": "2026-06-24T10:01:23+08:00",
    "created_at": "2026-06-24T10:00:00+08:00",
    "masked_card_number": "411111******1111",
    "trade_info": {
      "goods_name": "VIP Membership",
      "description": "Monthly subscription"
    },
    "metadata": "biz=member&uid=10001"
  }
}