# API Only

## 介绍

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

- 高度定制化
- 开发成本高


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

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


## 支持的支付方式

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


## 支付流程

### 明文卡交易

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


API: [Initiate Transaction](/zh-hans/payments/apis/payments/openapi/交易/payments-opl_1)

#### 请求示例


```json
{
  "merchant_id": "18356675194960",
  "payment_type": "PURCHASE",
  "authorisation_type": "FINAL_AUTH",
  "capture_method": "AUTOMATIC",
  "trans_id": "m1721xxx938999",
  "currency": "USD",
  "amount": "300",
  "return_url": "https://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": {
    // 消费者/客户信息
  }
}
```

### 卡信息加密组件

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


API: [Initiate Transaction](/zh-hans/payments/apis/payments/openapi/交易/payments-opl_1)

#### 请求示例


```json
{
    ...
    "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: 商户解密卡信息


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

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


### GooglePay

情况 1: 商户解密卡信息


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

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


## 3DS 处理

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

### 集成方式

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


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


请求示例


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

响应示例


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

## 消费与循环

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

### 集成方式

1. 目前 PayKKa 支持的循环支付需要由商户定期发起
2. 对于首次循环支付，需要 PayKKa 存储持卡人的卡信息，后续的循环支付只需要提供持卡人的 token 即可
3. 对于后续的循环支付，只需要提供持卡人的 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",
  "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](/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"
  }
}
```

## 欺诈检测

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

集成方式 [PayKKa Fraud Detection](/zh-hans/payments/docs/fraud/fraud-detection)

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

## 错误码

参见 [交易错误码](/zh-hans/payments/docs/developer-resources/transanction-error-code)

## 结果通知

参考 [Webhook](/zh-hans/payments/docs/developer-resources/webhook)