循环协议

介绍

如果您需要为消费者设置定期重复扣款，可通过 PayKKa 的循环支付功能轻松实现。在首次扣款时，指定存储银行卡信息，后续则可通过循环协议和 Token 完成后续的重复扣款，操作便捷且安全。

循环支付流程

API 发起循环支付

请求示例

{
  "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",
  "return_url": "https://url",
  "mit": false,
  "payment": {
    "payment_method": "BANKCARD",
    "store_payment_method": true,
    "token_usage": "SUBSCRIPTION",
    "shopper_reference": "854f5baaf0a735139c583c4cea14d14c",
    "exp_year": "2029",
    "exp_month": "08",
    "cvv": "579",
    "holder_name": "Yi Westrich",
    "card_no": "5555555555554444"
  }
}

收银台发起循环支付

创建收银台，参数要求存储支付方式 (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",
    "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
    }
  }
}

后续循环支付

需要指定 mit=true，表示商户发起交易

请求示例 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"
  }
}

循环协议管理

取消循环协议

取消循环协议需要使用Delete Recurring Agreement接口，需要提供 recurring_agreement_id 和 shopper_reference

取消循环协议不可恢复，请谨慎操作