# Drop-in iOS ## 介绍 嵌入式收银台支持将 PayKKa 的收银台支付组件嵌入您的移动应用界面，用于收集消费者的付款信息。 您可以通过 PayKKa APP SDK 组件创建自己的结账流程，消费者输入的付款信息仅在组件内传递，可以降低您的 PCI-DSS 合规性成本 ## 支持的支付方式 - Visa - MasterCard - JCB - American Express - Discover - Diners Club - Apple Pay ## 支付流程 Description of image 1. 客户在您的移动应用中访问结账界面，输入客户发货和账单等信息，点击支付按钮 2. 您由服务器发起支付请求用于创建收银台，您将得到收银台ID(session_id)用于后续加载收银台 3. 您使用收银台ID(`session_id`)和Client key(`client_key`)在应用界面内加载嵌入式收银台组件 4. 嵌入式收银台组件将动态显示支持的支付方式，客户选择支付方式后，点击支付按钮 5. 提交支付后，我们将处理所有可能的额外操作，如 3DS 认证或者第三方重定向页面 6. 支付处理完成后，将触发组件回调函数，您可以在此处处理支付结果 7. 您的webhook地址将收到支付结果通知（建议您接入交易查询获取支付结果） ## 接入流程 1. 获取您的交易密钥 2. 获取您的 Client key 3. 准备接入的通知地址 webhook ，提供到请求参数中或者设置在后台，将会在关键的支付节点发送通知给商户 4. 准备接入的跳转地址，提供到请求参数中，将会在收银台支付完成后跳转 5. 发起请求: [Create Session](/zh-hans/payments/apis/payments/openapi/收银台/session-opl_1)接口创建收银台，返回收银台ID 6. 接入移动端组件方式见 [iOS SDK](/zh-hans/payments/docs/developer-resources/native-sdks/ios-sdk/introduction) 7. 商户可以接入[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": "DROP_IN", # 收银台模式，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": "DROP_IN", "status": "PROCESSING", "currency": "HKD", "amount": "800", "expire_time": "2025-05-05T17:17:24+08:00", "authorisation_type": "FINAL_AUTH", "capture_method": "AUTOMATIC" } } ``` ### 添加 Drop-in 见 [iOS SDK](/zh-hans/payments/docs/developer-resources/native-sdks/ios-sdk/introduction) ### 收银台查询 查询收银台状态，通过收银台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": "DROP_IN", "status": "PROCESSING", "amount": "800", "currency": "HKD", "expire_time": "2025-05-05T17:17:24+08:00", "authorisation_type": "FINAL_AUTH", "capture_method": "AUTOMATIC" } } ``` 成功 ```json { "ret_code": "000000", "ret_msg": "Success", "data": { "merchant_id": "18356675194960", "trans_id": "m3246749195217", "session_id": "CS208760010022288125", "session_mode": "DROP_IN", "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" } } ``` 过期 ```json 超期未支付 { "ret_code": "000000", "ret_msg": "Success", "data": { "merchant_id": "18356675194960", "trans_id": "m3246749195217", "session_id": "CS208760010022288125", "session_mode": "DROP_IN", "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": "DROP_IN", "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": "COMPONENT", "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" } } ``` ## 3DS 处理 收银台产品无需您处理 3DS 认证，PayKKa 将全自动对支付安全进行智能化检测和处理，您只需关注支付结果即可 ## 有效期 收银台过期时间最大为 24 小时，过期后将无法继续支付；Drop-in 组件将收到回调事件 `onExpired`，您可以在该事件中提示用户支付已过期，并引导用户重新发起支付 若过期未发起支付，将不会有通知，查询收银台状态将得到 `status=EXPIRED`，查询交易状态将得到 `ret_msg=the order doesn't exist` ## 错误码 参见 [交易错误码](/zh-hans/payments/docs/developer-resources/transaction-error-code) ## 结果通知 参考 [Webhook](/zh-hans/payments/docs/developer-resources/webhook)