# 令牌化

## 介绍

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

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

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

## 令牌化优势

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


要使用卡组织（如 Visa 和 Mastercard）颁发的卡组织令牌进行付款，请参考 [Network Token](/zh-hans/payments/docs/token/network-token) 。

## 令牌化流程

### 快捷支付

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


请求示例
[Create Session](/zh-hans/payments/apis/payments/openapi/收银台/session-opl_1)


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

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


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


响应示例
[Query Payment](/zh-hans/payments/apis/payments/openapi/交易/payments-query-opl_1)


```json
{
  "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
    }
  }
}
```

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


请求示例
[Create Session](/zh-hans/payments/apis/payments/openapi/收银台/session-opl_1)


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

Description of image
### 循环支付

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


请求示例
[Create Session](/zh-hans/payments/apis/payments/openapi/收银台/session-opl_1)


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

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


响应示例
[Query Payment](/zh-hans/payments/apis/payments/openapi/交易/payments-query-opl_1)


```json
{
  "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
    }
  }
}
```

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


后续循环请求示例
[Initiate Transaction](/zh-hans/payments/apis/payments/openapi/交易/payments-opl_1)


```json
{
  "merchant_id": "18356675194960",
  "payment_type": "RECURRING",
  "authorisation_type": "FINAL_AUTH",
  "capture_method": "AUTOMATIC",
  "trans_id": "m3246749195217",
  "currency": "HKD",
  "amount": "800",
  "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](/zh-hans/payments/apis/payments/openapi/token/token-remove-opl_2)接口，需要提供 `token` 和 `shopper_reference`

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

### 查询令牌列表

查询令牌列表需要使用[Query Token List](/zh-hans/payments/apis/payments/openapi/token/token-query-opl)接口，需要提供 `shopper_reference`