• 简体中文
  • 捕获 / 取消授权

    适用市场:ZA 南非

    请求路径

    /api/v1/payment/merchant/card/operation

    对已授权的订单执行捕获(支付)或取消(解冻不扣款)。同一端点,通过 action 区分操作类型。

    前置条件:订单 orderStatus = 5 (required_capture) 时方可调用。

    请求参数

    参数类型必填说明
    amountintegercancel 必填;capture 选填操作金额(最小货币单位,分)
    currencystring是货币代码 ZAR
    idempotencyIdstring是幂等键,防止重复提交
    actionstring是capture 支付 · cancel 取消
    orderNostring是CreateOrder 返回的平台订单号
    userIdstring否商户侧用户标识
    nonceStrstring是随机字符串(参与签名)
    requestTimeinteger是Unix 毫秒时间戳(13 位)
    versionstring是2.0.0.0
    notifyUrlstring是异步通知接收地址(完整 URL)

    是 必填 · 否 选填

    action 枚举

    值含义资金流向
    capture支付从持卡人账户扣款至商户
    cancel取消解冻持卡人额度,不产生扣款

    返回值

    字段说明
    orderNo平台订单号
    idempotencyId幂等键回显
    orderStatus1 (pending) = 异步处理中,需查询或等通知确认最终结果
    currency货币代码,如 ZAR
    amount操作金额(最小货币单位,分)
    merchantId商户号

    示例

    capture(支付)

    curl 'https://open-gw-daily.palmpay-inc.com/api/v1/payment/merchant/card/operation' \
      -H 'CountryCode: ZA' -H 'Authorization: Bearer xxx' -H 'Content-Type: application/json' \
      -d '{"amount":10,"currency":"ZAR","idempotencyId":"c-001","action":"capture",
           "orderNo":"24260608092828582939","userId":"6545456","nonceStr":"xxx",
           "notifyUrl": "https://www.yoursite.com/callback/payment",
           "requestTime":1699925850000,"version":"2.0.0.0"}'

    cancel(取消)

    curl 'https://open-gw-daily.palmpay-inc.com/api/v1/payment/merchant/card/operation' \
      -H 'CountryCode: ZA' -H 'Authorization: Bearer xxx' -H 'Content-Type: application/json' \
      -d '{"amount":10,"currency":"ZAR","idempotencyId":"x-001","action":"cancel",
           "orderNo":"24260608092828582939","userId":"6545456","nonceStr":"xxx",
           "notifyUrl": "https://www.yoursite.com/callback/payment",
           "requestTime":1699925850000,"version":"2.0.0.0"}'

    响应

    {
      "respCode": "00000000",
      "respMsg": "success",
      "status": true,
      "data": {
        "orderNo": "24260701083336451596",
        "idempotencyId": "1782894800751",
        "orderStatus": 1,
        "currency": "ZAR",
        "amount": 1000,
        "merchantId": "124012503542121"
      }
    }

    订单状态流转

    createorder (captureMode=manual)
            │
            ▼
      orderStatus=5 (required_capture)
            │
       ┌────┴──────────┐
       │               │
       ▼               ▼
    capture          cancel
       │               │
       ▼               ▼
    status=2        status=4
    (succeeded)     (closed)

    注意事项

    1. 异步处理:同步响应 orderStatus=1 仅表示受理成功,最终结果需通过 订单查询或异步通知确认
    2. 幂等:通过 idempotencyId 保证重复调用不产生重复扣款
    3. cancel 不可逆:取消后授权金额释放回持卡人,无法恢复,需重新创建订单
    4. capture 金额:amount 必须 ≤ 授权金额