API Only

介绍

API Only 模式指商户的前端和后端通过调用 PayKKa 提供的 API 接口，自行构建支付流程与页面，支付请求和响应通过 API 交互完成，具有如下特点：

高度定制化
开发成本高

对于银行卡支付，我们接受下面两种 API 方案

使用卡信息加密组件 Encrypted Card ，对卡片信息进行安全加密。这有助于您符合 PCI 合规要求。
直接收集并传输原始明文卡数据。这种方式需要您拥有 PCI DSS 资质。如果您希望使用这种模式，请联系您的客户经理提供 PCI 资质。
接入 Encrypted Card 需要提供您的域名解除跨域限制。

支持的支付方式

Visa
MasterCard
JCB
American Express
Discover
Diners Club
Apple Pay
Google Pay

支付流程

明文卡交易

获取您的交易密钥
获取您的 Client key (针对 Encrypted Card 接入需要)。
准备接入的通知地址 webhook ，提供到请求参数中，将会在关键的支付节点发送通知给商户。
准备接入的跳转地址 webhook ，提供到请求参数中，将会在 3DS 认证触发后跳转。
发起请求。
是否需要消费者进行 3DS 认证可根据支付或者查询接口的响应字段 authentication_result.authentication_url，返回代表正在等待消费者进行 3DS 认证。

API: Initiate Transaction

请求示例

{
  "merchant_id": "18356675194960",
  "payment_type": "PURCHASE",
  "authorisation_type": "FINAL_AUTH",
  "capture_method": "AUTOMATIC",
  "trans_id": "m1721xxx938999",
  "timestamp": 1742816738605,
  "currency": "USD",
  "amount": "300",
  "notify_url": "https://notify_url",
  "return_url": "https://notify_url",
  "payment": {
    "payment_method": "BANKCARD",
    "shopper_reference": "myuserid001",
    "card_no": "4242424242424242",
    "exp_year": "2031",
    "exp_month": "07",
    "cvv": "123",
    "holder_name": "lisa"
  },
  "authentication": {
    "challenge_indicator": "AUTO"
  },
  "browser": {
    // 消费者终端信息
  },
  "goods": [
    // 商品信息
  ],
  "bill": {
    // 账单信息
  },
  "shipping": {
    // 收货信息, 实物贸易必填
  },
  "customer": {
    // 消费者/客户信息
  }
}

卡信息加密组件

获取您的交易密钥
获取您的 Client key (针对 Encrypted Card 接入需要)。
准备接入的通知地址 webhook ，提供到请求参数中，将会在关键的支付节点发送通知给商户。
准备接入的跳转地址 webhook ，提供到请求参数中，将会在 3DS 认证触发后跳转。
发起请求。
是否需要消费者进行 3DS 认证可根据支付或者查询接口的响应字段 authentication_result.authentication_url，返回代表正在等待消费者进行 3DS 认证。
接入组件流程见 Encrypted Card。

API: Initiate Transaction

请求示例

{
    ...
    "payment": {
        "payment_method": "BANKCARD",
        "shopper_reference": "myuserid001",
        "encrypted_card_no": "MTc0MjczNjg1Nxxxx",
        "encrypted_exp_year": "Wt938LfJ2Pxxxxx",
        "encrypted_exp_month": "WfRto3qWfidnxxx",
        "encrypted_cvv": "MEal81oshxxx",
        "holder_name": "lisa"
    },
    ...
}

ApplePay

情况 1: 商户解密卡信息

{
    ...
    "payment": {
        "payment_method": "APPLE_PAY",
        "shopper_reference": "myuserid001",
        "card_no": "4242424242424242",
        "exp_year": "2031",
        "exp_month": "07",
        "cvv": "123",
        "holder_name": "lisa",
        "token_authentication": {
          "cryptogram": "ALbOGff2RLbTADtP3BuIAoABFA==",
          "token_format": "cryptogram_3ds",
          "eci": "07"
        }
    }
    ...

情况 2: 商户不解密卡信息

{
    ...
    "payment": {
        "payment_method": "APPLE_PAY",
        "shopper_reference": "myuserid001",
        "token_data": "token from ApplePay SDK"
    },
    ...
}

ApplePay 目前支持两种接入方式：1.商户接入 ApplePay 解密卡信息，则可以发送明文卡信息给 PayKKa；2.商户不解密，则商家需要接入 Create Apple Pay Session 接口以加载 ApplePay 组件，并最终发送 ApplePay 组件生成的支付 token(json 字符串)给 PayKKa 做解密并交易。
接入 ApplePay 详细流程见 ApplePay。

GooglePay

情况 1: 商户解密卡信息

{
    ...
    "payment": {
        "payment_method": "GOOGLE_PAY",
        "shopper_reference": "myuserid001",
        "card_no": "4242424242424242",
        "exp_year": "2031",
        "exp_month": "07",
        "cvv": "123",
        "holder_name": "lisa",
        "token_authentication": {
          "cryptogram": "ALbOGff2RLbTADtP3BuIAoABFA==",
          "token_format": "CRYPTOGRAM_3DS",
          "eci": "02",
          "account_verified": true,
          "card_holder_authenticated": true
        }
    }
    ...

情况 2: 商户不解密卡信息

{
    ...
    "payment": {
        "payment_method": "GOOGLE_PAY",
        "shopper_reference": "myuserid001",
        "token_data": "token from GooglePay SDK"
    },
    ...
}

GooglePay 目前支持两种接入方式；1.商户接入 GooglePay 解密卡信息，则可以发送明文卡信息给 PayKKa；2.商户不解密，则可以发送 GooglePay 组件生成的支付 token (json 字符串)给 PayKKa 做解密并交易。
接入 GooglePay 详细流程见 GooglePay。

3DS 处理

3DS 验证为信用卡和借记卡的线上交易提供智能安全防护，通过实时身份核验确保交易安全。在支付过程中，系统会引导持卡人完成发卡行的安全认证，从而在提升交易安全性的同时，将潜在的欺诈风险责任转移至发卡机构，为商户提供更可靠的支付保障。

集成方式

请求: 可以通过 API 参数 authentication 指明 3DS 验证倾向，但是其后续验证处理由卡组和发卡行综合决定。
响应: 对 PayKKa 的 API 响应进行解析，跳转到其中 3DS 验证地址，后续交由 PayKKa 完成后续的 3DS 验证流程。

3DS 验证结果会通过 PayKKa 的 webhook 通知给商户，商户可以根据通知结果进行后续处理;

请求示例

{
    ...
    "authentication": {
        "challenge_indicator": "AUTO"
    },
    ...
}

响应示例

{
    "ret_code": "000000",
    "ret_msg": "Success",
    "data": {
        ...
        "status": "PROCESSING",
        "authentication_result": {
            "authentication_url": "https://3ds_path_url"
        },
        "payment": {
            "payment_method": "BANKCARD"
        },
        ...
    }
}

消费与循环

如果您的付款要求按照一定周期(如每月、每年或自定义时间间隔)从客户的银行卡或电子钱包中重复扣款，无需客户每次手动授权，您可以使用 PayKKa 的循环支付功能。

集成方式

目前 PayKKa 支持的循环支付需要由商户定期发起
对于首次循环支付，需要 PayKKa 存储持卡人的卡信息，后续的循环支付只需要提供持卡人的 token 即可
对于后续的循环支付，只需要提供持卡人的 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",
  "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"
  },
  "browser": {
    // 消费者终端信息
  },
  "goods": [
    // 商品信息
  ],
  "bill": {
    // 账单信息
  },
  "shipping": {
    // 收货信息, 实物贸易必填
  },
  "customer": {
    // 消费者/客户信息
  }
}

后续循环请求示例 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"
  }
}

欺诈检测

Fraud Detection 是一种嵌入在网站或支付页面中的 JavaScript 代码，用于实时收集用户行为数据、设备信息和交易环境，帮助支付系统或风控平台识别潜在的欺诈交易

集成方式 PayKKa Fraud Detection

强烈建议集成 PayKKa 的 Fraud Detection SDK，可以显著降低欺诈和拒付风险，提高支付成功率

错误码

参见交易错误码

结果通知

参考 Webhook