令牌化

介绍

使用 PayKKa 付款时，可以开启使消费者在支付过程中由 PayKKa 存储消费者的一个或多个支付数据 (须消费者同意)，这些信息可以用于快捷支付或者循环支付; 这样可以极大提高支付效率和成功率，同时减少消费者支付的复杂度，提升消费者支付体验，以及方便的进行订阅付款。

我们将这些保存的支付数据称为令牌，整个支付过程中支付数据的存储称为令牌化，并使用 token 标识它们。

我们支持多种支付方式的令牌化，包括卡/ApplePay/GooglePay/SEPA 直接借记等。

令牌化优势

允许消费者存储他们的付款详细信息，提升消费者支付体验
在循环支付场景下，可以方便后续自动的订阅付款
减少支付失败率，提升支付成功率
减少您的 PCI-DSS 合规成本，提高安全性，减少支付卡信息泄露风险

要使用卡组织（如 Visa 和 Mastercard）颁发的卡组织令牌进行付款，请参考 Network Token 。

令牌化流程

快捷支付

创建收银台（或者 API 支付接口），参数要求存储支付方式（store_payment_method=true）。

请求示例 Create Session

{
  "merchant_id": "18356675194960",
  "payment_type": "PURCHASE",
  "trans_id": "m826xxx66465",
  "timestamp": 1746420181806,
  "expire_time": "2025-05-05T17:17:24+08:00",
  "session_mode": "HOSTED",
  "currency": "HKD",
  "amount": "800",
  "notify_url": "https://url",
  "return_url": "https://url",
  "payment": {
    "store_payment_method": true,
    "token_usage": "CARD_ON_FILE",
    "shopper_reference": "854f5baaf0a735139c583c4cea14d14c"
  }
}

消费者支付时，选择快捷支付，并同意存储支付方式（消费者勾选同意才进行令牌化）。

支付成功后，若消费者勾选同意，则支付数据被 PayKKa 存储为令牌，（可通过交易查询接口获取 token）。

响应示例 Query Payment

{
  "ret_code": "000000",
  "ret_msg": "Success",
  "data": {
    "error_code": "0000",
    "error_description": "request success",
    "merchant_id": "18356675194960",
    "trans_id": "m826xxx66465",
    "order_id": "GW206xxx28702",
    "status": "SUCCESS",
    "authorisation_type": "FINAL_AUTH",
    "capture_method": "AUTOMATIC",
    "amount": 8715,
    "currency": "EUR",
    "pay_finish_time": "2025-05-08T15:34:14+08:00",
    "token": "TK20535xxxx8947",
    "shopper_reference": "f4911bc8b17106a08f2f7a89a9fc4d11",
    "expire_time": "2025-05-08T19:24:49+08:00",
    "session_id": "CS206304436949400769",
    "payment": {
      "payment_method": "BANKCARD"
    },
    "card_info": {
      "bin": "400000",
      "last4": "3220",
      "card_brand": "VISA"
    },
    "balances": {
      "authed_amount": 8715,
      "captured_amount": 8715,
      "able_to_capture_amount": 0,
      "voided_amount": 0,
      "able_to_void_amount": 0,
      "refunded_amount": 0,
      "able_to_refund_amount": 8715
    }
  }
}

再次创建收银台支付时，可以选择快捷支付，并选择已存储的令牌，输入 CVV 可直接支付。

请求示例 Create Session

{
  "merchant_id": "18356675194960",
  "payment_type": "PURCHASE",
  "trans_id": "m826xxx66465",
  "timestamp": 1746420181806,
  "expire_time": "2025-05-05T17:17:24+08:00",
  "session_mode": "HOSTED",
  "currency": "USD",
  "amount": "100",
  "notify_url": "https://url",
  "return_url": "https://url",
  "payment": {
    "shopper_reference": "854f5baaf0a735139c583c4cea14d14c"
  }
}

循环支付

创建收银台，参数要求存储支付方式（store_payment_method=true）。

请求示例 Create Session

{
  "merchant_id": "18356675194960",
  "payment_type": "RECURRING",
  "trans_id": "m826xxx66465",
  "timestamp": 1746420181806,
  "expire_time": "2025-05-05T17:17:24+08:00",
  "session_mode": "HOSTED",
  "currency": "HKD",
  "amount": "800",
  "notify_url": "https://url",
  "return_url": "https://url",
  "payment": {
    "store_payment_method": true,
    "token_usage": "SUBSCRIPTION",
    "shopper_reference": "854f5baaf0a735139c583c4cea14d14c"
  }
}

消费者支付时，会提示消费者将对支付数据进行令牌话（不可取消）。
支付成功后，可得到循环协议 id，支付数据被 PayKKa 存储为令牌，可通过交易查询接口获取 token。

响应示例 Query Payment

{
  "ret_code": "000000",
  "ret_msg": "Success",
  "data": {
    "error_code": "0000",
    "error_description": "request success",
    "merchant_id": "18356675194960",
    "trans_id": "m826xxx66465",
    "order_id": "GW206xxx28702",
    "status": "SUCCESS",
    "authorisation_type": "FINAL_AUTH",
    "capture_method": "AUTOMATIC",
    "amount": 8715,
    "currency": "EUR",
    "pay_finish_time": "2025-05-08T15:34:14+08:00",
    "token": "TK20535xxxx8947",
    "recurring_agreement_id": "RA4264524535435435",
    "shopper_reference": "f4911bc8b17106a08f2f7a89a9fc4d11",
    "expire_time": "2025-05-08T19:24:49+08:00",
    "session_id": "CS206304436949400769",
    "payment": {
      "payment_method": "BANKCARD"
    },
    "card_info": {
      "bin": "400000",
      "last4": "3220",
      "card_brand": "VISA"
    },
    "balances": {
      "authed_amount": 8715,
      "captured_amount": 8715,
      "able_to_capture_amount": 0,
      "voided_amount": 0,
      "able_to_void_amount": 0,
      "refunded_amount": 0,
      "able_to_refund_amount": 8715
    }
  }
}

当商户通过 API 定期发起后续循环支付，可以使用令牌标识（token）进行直接扣款而无需消费者再次授权。

后续循环请求示例 Initiate Transaction

{
  "merchant_id": "18356675194960",
  "payment_type": "RECURRING",
  "authorisation_type": "FINAL_AUTH",
  "capture_method": "AUTOMATIC",
  "trans_id": "m3246749195217",
  "timestamp": 1746420181806,
  "currency": "HKD",
  "amount": "800",
  "notify_url": "https://url",
  "mit": true,
  "recurring_agreement_id": "RA4264524535435435",
  "payment": {
    "payment_method": "BANKCARD",
    "shopper_reference": "558b5cb1b8cbcc8496062155c69cf2ab",
    "token": "TK20231435132143229"
  }
}

令牌管理

令牌用途

字段: token_usage

目前 PayKKa 支持的令牌用途包括:

CARD_ON_FILE: 消费者出现的支付（主要用于消费支付场景下的快捷支付）。
SUBSCRIPTION: 订阅（用于订阅支付场景下的循环支付，包括 API 和收银台）。

删除令牌

删除令牌需要使用Delete Token接口，需要提供 token 和 shopper_reference

删除令牌不可恢复，请谨慎操作

查询令牌列表

查询令牌列表需要使用Query Token List接口，需要提供 shopper_reference