# Hosted ## 介绍 收银台产品是一款集成多种支付方式的智能系统，其由商户发起创建收银台，可以指定部分参数（如金额，货币，支付方式）并且无需对消费者流程做任何处理。支持多种支付方式。 - 开发简单，部署快 - 无需 PCI 认证，敏感信息令牌化，保证消费者支付安全 - 可以自定义收银台页面的部分样式和 logo（请联系您的客户经理配置） - 内置 3DS 认证支持，无需商户处理 - 动态显示支持的支付方式，无需额外开发 - 响应式页面设计，适配多种设备，支持多国语言 br 对于使用收银台支付，我们提供了三种接入方式： 1. Hosted: 单页面收银台，提供完整的 url 供消费者跳转后支付; 只需最少的集成花销和最简单的处理 2. Drop-in: 嵌入式收银台，可集成到商户页面，支持一定的定制化 3. Component: 组件式收银台，可无缝融入商户页面，可高度定制化 ## 模式差异 | | Hosted | Drop-in | Component | | --- | --- | --- | --- | | 集成方式 | 跳转至 PayKKa 提供的独立支付页面 | 直接嵌入商户网站/App 的页面中 | 直接嵌入商户网站/App 的页面中 | | 定制化程度 | 弱，依赖支付服务商的主题模板 | 中，商户进行一定的 UI 定制和一定程度交互流程 | 强，商户可高度定制 UI 和交互流程 | | 技术要求 | 较低，仅需集成 API | 适中，需集成 API 和前端组件 | 较高，需集成 API 和前端组件，可自定义组合 | | 灵活性 | 来源于 PayKKa 能力，功能相对固定 | 来源于商户集成，可以提供较为丰富的功能 | 来源于商户集成，可以提供最丰富的功能 | | 用户体验 | 页面跳转，需离开商户网站到新页面 | 无缝体验，全程在商户网站完成支付 | 无缝体验，全程在商户网站完成支付 | | 信任度 | 依赖于商户及 PayKKa 品牌站点支付信任 | 依赖于商户站点建立支付信任 | 依赖于商户站点建立支付信任 | ## 支持的支付方式 - Visa - MasterCard - JCB - American Express - Discover - Diners Club - Apple Pay - Google Pay - WechatPay - Alipay+ - GCash - Maya (Paymaya) - ShopeePay - GrabPay - Zalopay - VietQR ## 支付流程 Description of image 1. 客户访问您的结账页面，输入客户发货和账单等信息，点击支付按钮 2. 您由服务器发起支付请求用于创建收银台，您将得到收银台页面 URL并引导客户跳转至收银台页面 3. 收银台页面将动态显示支持的支付方式，客户选择支付方式后，点击支付按钮 4. 提交支付后，我们将处理所有可能的额外操作，如 3DS 认证或者第三方重定向页面 5. 支付处理完成后，客户被重定向至您的重定向地址 6. 您的webhook地址将收到支付结果通知（建议您接入交易查询获取支付结果） ## 接入流程 1. 获取您的交易密钥 2. 准备接入的通知地址 webhook，提供到请求参数中或者设置在后台，将会在关键的支付节点发送通知给商户 3. 准备接入的跳转地址，提供到请求参数中，将会在收银台支付完成后跳转 4. 发起请求: [Create Session](/zh-hans/payments/apis/payments/openapi/收银台/session-opl_1)接口创建收银台，返回收银台页面 URL 5. 商户可以接入[Query Session](/zh-hans/payments/apis/payments/openapi/收银台/session-query-opl_2)接口获取收银台结果，或者可以直接接入[Query Transaction](/zh-hans/payments/apis/payments/openapi/交易/payments-query-opl_1)接口获取订单结果(若最终无结果表示消费者未发起交易) PayKKa 的收银台 (标识: `session_id`) 代表页面形式的支付意向，最终的支付结果由交易 (标识: `order_id`) 结果决定，因此您需要关注订单的最终状态以确定支付结果 收银台查询: 用于查询收银台的状态和支付结果，若消费者未发起支付，则不会产生交易订单 交易查询: 用于查询交易订单的支付结果，订单终态后会通过 webhook 通知 Description of image ### 创建收银台 当客户准备支付时，发送服务端请求可以创建一个Session和对应链接，通过Session来发起支付请求 请求示例 [Create Session](/zh-hans/payments/apis/payments/openapi/收银台/session-opl_1) ```json { "merchant_id": "18356675194960", "payment_type": "PURCHASE", "authorisation_type": "FINAL_AUTH", "capture_method": "AUTOMATIC", "trans_id": "m3246749195217", "expire_time": "2025-05-05T17:17:24+08:00", "session_mode": "HOSTED", # 收银台模式，HOSTED: 托管, DROP_IN: 嵌入, COMPONENT: 组件 "display_locale": "fr-FR", "currency": "HKD", "amount": "800", "return_url": "https://url", "payment": { "store_payment_method": true, # 是否存储卡信息并令牌化,将得到token；true: 存储, false: 不存储 "token_usage": "CARD_ON_FILE" "shopper_reference": "854f5baaf0a735139c583c4cea14d14c" }, "goods": [ // 商品信息 ], "bill": { // 账单信息 }, "shipping": { // 收货信息, 实物贸易必填 }, "customer": { // 消费者/客户信息 } } ``` 响应示例 ```json { "ret_code": "000000", "ret_msg": "Success", "data": { "merchant_id": "18356675194960", "trans_id": "m3246749195217", "session_id": "CS208760010022288125", "session_mode": "HOSTED", "status": "PROCESSING", "currency": "HKD", "amount": "800", "expire_time": "2025-05-05T17:17:24+08:00", "authorisation_type": "FINAL_AUTH", "capture_method": "AUTOMATIC", "session_url": "https://checkout.aq.paykka.com/hp/pay/CS208760010022288125" } } ``` ### 收银台查询 查询收银台状态，通过收银台ID(`session_id`)查询 请求示例 [Query Session](/zh-hans/payments/apis/payments/openapi/收银台/session-query-opl_2) ```json { "merchant_id": "18356675194960", "trans_id": "m3246749195217", # trans_id/session_id二选一 "session_id": "CS208760010022288125" } ``` 响应示例 处理中 ```json { "ret_code": "000000", "ret_msg": "Success", "data": { "merchant_id": "18356675194960", "trans_id": "m3246749195217", "session_id": "CS208760010022288125", "session_mode": "HOSTED", "status": "PROCESSING", "amount": "800", "currency": "HKD", "expire_time": "2025-05-05T17:17:24+08:00", "authorisation_type": "FINAL_AUTH", "capture_method": "AUTOMATIC", "session_url": "https://checkout.aq.paykka.com/hp/pay/CS208760010022288125" } } ``` 成功 ```json { "ret_code": "000000", "ret_msg": "Success", "data": { "merchant_id": "18356675194960", "trans_id": "m3246749195217", "session_id": "CS208760010022288125", "session_mode": "HOSTED", "status": "SUCCESS", # 收银台状态 "order_status": "SUCCESS", # 交易状态 "error_code": "0000", # 交易错误码 "error_description": "request success", "order_id": "GW208760010022288125", # 交易订单号 "amount": "800", "currency": "HKD", "expire_time": "2025-05-05T17:17:24+08:00", "authorisation_type": "FINAL_AUTH", "capture_method": "AUTOMATIC", "session_url": "https://checkout.aq.paykka.com/hp/pay/CS208760010022288125" } } ``` 过期 ```json 超期未支付 { "ret_code": "000000", "ret_msg": "Success", "data": { "merchant_id": "18356675194960", "trans_id": "m3246749195217", "session_id": "CS208760010022288125", "session_mode": "HOSTED", "status": "EXPIRED", # 收银台状态 "amount": "800", "currency": "HKD", "expire_time": "2025-05-05T17:17:24+08:00" } } 支付失败 { "ret_code": "000000", "ret_msg": "Success", "data": { "merchant_id": "18356675194960", "trans_id": "m3246749195217", "session_id": "CS208760010022288125", "session_mode": "HOSTED", "status": "EXPIRED", # 收银台状态 "amount": "800", "currency": "HKD", "order_status": "FAILURE", # 交易状态 "error_code": "0000", # 交易错误码 "error_description": "request success", "order_id": "GW208760010022288125", # 交易订单号 "expire_time": "2025-05-05T17:17:24+08:00" } } ``` ### 交易查询 查询交易状态，通过交易ID(`order_id`)查询 请求示例 [Query Transaction](/zh-hans/payments/apis/payments/openapi/交易/payments-query-opl_1) ```json { "merchant_id": "18356675194960", "trans_id": "m3246749195217", # session_id/order_id/trans_id三选一 "session_id": "CS208760010022288125", "order_id": "GW208760010022288125" } ``` 响应示例 ```json { "ret_code": "000000", "ret_msg": "Success", "data": { "merchant_id": "18356675194960", "trans_id": "m3246749195217", "order_id": "GW208760010022288125", "session_id": "CS208760010022288125", "status": "SUCCESS", # 交易状态 "error_code": "0000", # 交易错误码 "error_description": "request success", "amount": "800", "currency": "HKD", "pay_finish_time": "2025-05-05T17:17:24+08:00" } } ``` ## 消费与循环 如果您的付款要求按照一定周期(如每月、每年或自定义时间间隔)从客户的银行卡或电子钱包中重复扣款，无需客户每次手动授权，您可以使用 PayKKa 的循环支付功能。 ### 集成方式 1. 目前 PayKKa 支持的循环支付需要由商户定期发起 2. 对于首次循环支付，需要 PayKKa 存储持卡人的卡信息，后续的循环支付只需要提供持卡人的 token 即可 3. 对于后续的循环支付，只需要提供持卡人的 token 即可，无需重复提供卡信息 首次循环请求示例 [Create Session](/zh-hans/payments/apis/payments/openapi/收银台/session-opl_1) ```json { "merchant_id": "18356675194960", "payment_type": "RECURRING", "authorisation_type": "FINAL_AUTH", "capture_method": "AUTOMATIC", "trans_id": "m3246749195217", "expire_time": "2025-05-05T17:17:24+08:00", "session_mode": "HOSTED", "display_locale": "fr-FR", "currency": "HKD", "amount": "800", "return_url": "https://url", "mit": false, "payment": { "store_payment_method": true, "token_usage": "SUBSCRIPTION", "shopper_reference": "854f5baaf0a735139c583c4cea14d14c" }, "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" } } ``` ## 存储卡信息 PayKKa 已通过 PCI-DSS 的 1 级认证，拥有完整且安全的持卡人数据加密存储方案，并且不会存储持卡人敏感数据 PayKKa 目前提供两种存储卡信息形式，以提供给商户和消费者更好的体验 - 快捷支付: 创建收银台可以要求存储卡信息以为当前消费者下次支付(非循环)提供更加流畅顺滑的支付体验，下次支付(收银台形式)时无需再次输入卡信息，仅输入 CVV 即可，如下图 请求示例 ```json { ... "payment": { "store_payment_method": true, "token_usage": "CARD_ON_FILE", "shopper_reference": "854f5baaf0a735139c583c4cea14d14c" }, ... } ``` - 循环支付: 创建循环收银台强制要求存储卡信息，下次支付(循环)时需携带 token 作为支付凭证 请求示例 ```json { ... "payment": { "store_payment_method": true, "token_usage": "SUBSCRIPTION", "shopper_reference": "854f5baaf0a735139c583c4cea14d14c" }, ... } ``` ## 3DS 处理 收银台产品无需您处理 3DS 认证，PayKKa 将全自动对支付安全进行智能化检测和处理，您只需关注支付结果即可 Description of image ## 有效期 收银台过期时间最大为 24 小时，过期后将无法继续支付；消费者可点击左上角返回按钮跳回商户网站 若过期未发起支付，将不会有通知，查询收银台状态将得到 `status=EXPIRED`，查询交易状态将得到 `ret_msg=the order doesn't exist` Description of image ## 错误码 参见 [交易错误码](/zh-hans/payments/docs/developer-resources/transanction-error-code) ## 结果通知 参考 [Webhook](/zh-hans/payments/docs/developer-resources/webhook)