• 简体中文
  • 独立绑卡

    适用市场:ZA 南非

    /api/v1/card/token/bind

    不产生支付交易,仅零金额验证并绑定卡片,返回可用于后续支付的 cardToken。绑卡时将触发零金额授权 + 3DS 认证。

    典型场景:MIT 递归扣款前置、一键支付预绑卡、钱包卡管理。

    请求参数

    参数类型必填说明
    cardNostring是卡号
    expiryMonthstring是有效期月
    expiryYearstring是有效期年(后两位)
    cvvstring是CVV/CVC2
    holderNamestring否持卡人姓名
    userIdstring否商户侧用户标识
    callBackUrlstring否3DS 完成后浏览器跳转地址
    nonceStrstring是随机字符串(参与签名)
    requestTimeinteger是Unix 毫秒时间戳
    versionstring是2.0.0.0

    是 必填 · 否 选填

    返回值

    字段说明
    cardToken卡 Token,可用于 [CreateOrder] Token 支付模式
    verifyMethod固定 open_url
    verifyUrl3DS 认证 URL(需引导持卡人完成身份验证)

    示例

    请求 / 响应

    curl 'https://open-gw-daily.palmpay-inc.com/api/v1/card/token/bind' \
      -H 'CountryCode: ZA' -H 'Authorization: Bearer xxx' -H 'Content-Type: application/json' \
      -d '{"cardNo":"4000000000000002","expiryMonth":"12","expiryYear":"26","cvv":"123",
           "holderName":"zhangg","userId":"6545456",
           "callBackUrl":"http://baidu.com","nonceStr":"xxx","requestTime":16999258500,"version":"2.0.0.0"}'
    {
      "respCode": "00000000",
      "respMsg": "success",
      "status": true,
      "data": {
        "cardToken": "60871b47d2e7444b859848c567824bfd",
        "verifyMethod": "open_url",
        "verifyUrl": "https://.../3ds-auth-html?..."
      }
    }

    通知回调(Notification Callback)

    绑卡流程(含 3DS 认证)完成后,PalmPay 会向商户在开放平台后台配置的通知地址发送 POST 请求,告知绑卡结果。

    ⚠️ 注意区分:callBackUrl 是 3DS 完成后浏览器跳转的前端地址;通知回调是 PalmPay 服务端 → 商户服务端的异步通知,两者用途不同。

    请求方式

    • Method: POST
    • Content-Type: application/json
    • countryCode: ZA

    通知参数

    字段类型说明
    bankNamestring发卡行名称
    cardBrandstring卡组织(如 VISA、MASTERCARD)
    cardCountrystring卡所属国家代码(如 ZA)
    cardLast4string卡号后 4 位
    cardNostring脱敏卡号
    cardTokenstring绑定的卡 Token,用于后续 Token 支付
    cardTypestring卡类型(debit_card / credit_card)
    createTimestring绑卡创建时间(UTC ISO 8601)
    expiryMonthstring有效期月
    expiryYearstring有效期年(后两位)
    tokenStatusstringToken 状态
    updateTimestring更新时间(UTC ISO 8601)
    signstring签名值(URL 编码,验签前需先 decode)

    通知示例

    {
      "bankName": "Wema Bank",
      "cardBrand": "VISA",
      "cardCountry": "ZA",
      "cardLast4": "2105",
      "cardNo": "400000******2105",
      "cardToken": "8162f22fd3944fefea92e5s8eb38ee942",
      "cardType": "debit_card",
      "createTime": "2026-09-10T02:18:26+00:00",
      "expiryMonth": "12",
      "expiryYear": "26",
      "tokenStatus": "1",
      "updateTime": "2026-09-10T02:18:26+00:00",
      "sign": "Uwa7FfghHpJx4CYdEt82BYRDPsXvsthLwF7rcpufjbBcSVuPateZAEYyAzoAMts2F7AQbaV8TVTFaQSjAASNl8i5NfrqSqeCEzYAiFVu8ODD5tqX3JCVPfFQZhL05Z32VH0qBv1%2Bpcr9LZguEBdn5lh5buJVe3ICKue63O..."
    }

    验签说明

    回调通知的 sign 字段使用与请求签名相同的算法生成,商户应使用 PalmPay 公钥 进行验签:

    1. 对 sign 值做 URL Decode(值中含 %2F=/、%2B=+,需完整 decode)
    2. 将除 sign 外的所有非空参数按 key ASCII 升序拼接 key=value&key=value
    3. MD5(strA).toUpperCase() → md5Str
    4. 用 PalmPay 公钥 SHA1WithRSA 验签 md5Str,与 decode 后的 sign 比对

    ⚠️ sign 编码注意:实际 sign 值中同时存在 URL 编码字符(%2F、%2B)和未编码的 /,decode 时需使用标准 URL decode(如 Java URLDecoder.decode),不要手动替换。

    验签失败的通知应视为无效,不予处理。

    重试机制

    若商户未在规定时间内返回成功应答,PalmPay 将按策略自动重试通知。

    商户应答要求

    商户收到通知并完成处理后,应返回约定的成功应答,否则 PalmPay 将持续重试直至达到上限。

    绑卡 → Token 支付完整流程

    商户                          PalmPay                        卡组织
     │                              │                             │
     │ ① POST /card/token/bind      │                             │
     │    传入卡号+CVV等             │                             │
     │ ────────────────────────────→│  发起 $0 授权 + 3DS          │
     │ ←── cardToken + verifyUrl    │ ───────────────────────────→│
     │                              │                             │
     │ ② 持卡人跳转 verifyUrl        │                             │
     │    完成 3DS 认证              │                             │
     │                              │  卡绑定成功                   │
     │                              │                             │
     │ ③ POST /createorder          │                             │
     │    cardPayerInfo:            │                             │
     │    {"cardToken":"xx"}        │                             │
     │ ────────────────────────────→│  使用已绑 Token 支付         │
     │ ←── orderNo(无需再 3DS)     │                             │