diff --git a/src/document/cn/apidoc.json b/src/document/cn/apidoc.json index 567b6e3d3..c07257310 100644 --- a/src/document/cn/apidoc.json +++ b/src/document/cn/apidoc.json @@ -22,6 +22,10 @@ "Miniprogram_Payment", "NewMobileH5Pay", "MobileH5Pay", + "CardPayment", + "CardPreOrder", + "CardInputView", + "CardOrder", "RetailPay", "RetailMicroPay", "RetailQRCode", diff --git a/src/document/cn/apis.js b/src/document/cn/apis.js index 36c8acdfb..cc1a54d19 100644 --- a/src/document/cn/apis.js +++ b/src/document/cn/apis.js @@ -230,7 +230,119 @@ * @apiError (ERROR_CODE) ORDER_NOT_EXIST 订单不存在 * @apiError (ERROR_CODE) ORDER_MISMATCH 订单号与商户不匹配 */ - +/** + * @api {PUT} /api/v1.0/gateway/partners/{partner_code}/pre_card_orders/{order_id} 创建卡支付预订单 + * @apiName CardPreOrder + * @apiGroup CardPayment + * @apiVersion 1.0.0 + * @apiDescription + * + * 卡支付即消费者输入银行卡信息进行下单的接口，接入卡支付需要额外的合规流程。
+ * 卡支付预订单是先下单，然后跳转royalpay支付页由消费者输入卡信息并完成支付
+ * 卡支付预订单允许消费者多次尝试输入，因此除非主动关闭订单，订单有效期会一直持续到有效期结束。 + * + * @apiHeader Accept application/json + * @apiHeader Content-Type application/json + * @apiParam (PathVariable) {String} partner_code 必填，商户编码，由4位大写字母或数字构成 + * @apiParam (PathVariable) {String} order_id 必填，商户支付订单号，要求同一商户唯一 + * @apiUse Sign + * @apiParam (JSON) {String} description 必填，订单标题（最大长度128字符，超出自动截取） + * @apiParam (JSON) {int} price 必填，金额，单位为货币最小单位，例如使用100表示AUD1.00 + * @apiParam (JSON) {String=AUD,CNY} currency=AUD 币种代码，卡支付仅支持AUD下单 + * @apiParam (JSON) {String} notify_url 支付通知url，详见支付通知api，不填则不会推送支付通知 + * @apiParam (JSON) {String} operator 操作人员标识 + * @apiParam (JSON) {Boolean} domestic_only 默认为false，是否只允许本国卡。由于境内境外卡支付手续费差异巨大，可在此限制。 + * @apiParam (JSON) {Boolean} disable_credit_card 默认为false，如果希望限制消费者使用信用卡支付可传入true + * @apiParam (JSON) {String} customer_id 可选参数，如果事先进行了tokenize操作可提供customer id，消费者随后仅需输入cvv信息 + * @apiParam (JSON) {JSON} customer 可选参数，提交消费者基本信息，可为charge back发生时提供依据 + * + * @apiParam (customer) {String} name 姓名，可选，如果未提供会自动使用card holder name + * @apiParam (customer) {String} postcode 邮编，可选，4位数字 + * @apiParam (customer) {String} address 地址，可选 + * @apiParam (customer) {String} city 城市，如Sydney + * @apiParam (customer) {String} state 州，可选，三位大写代码，如VIC + * @apiParam (customer) {String} country 国家，可选，ISO-3600-1标准收录的两位国家代码 + * + * @apiSuccess {String} return_code 执行结果 + * @apiSuccess {String} result_code SUCCESS表示创建订单成功，EXISTS表示订单已存在 + * @apiSuccess {String} partner_code 商户编码 + * @apiSuccess {String} channel 支付渠道 + * @apiSuccess {String} full_name 商户注册全名 + * @apiSuccess {String} partner_name 商户名称 + * @apiSuccess {String} order_id RoyalPay订单ID，同时也是支付渠道订单ID，最终支付成功的订单ID可能不同 + * @apiSuccess {String} partner_order_id 商户订单ID + * @apiSuccess {String} pay_url 跳转URL + * + * @apiUse GlobalError + * @apiError (ERROR_CODE) ORDER_MISMATCH 订单号与商户不匹配 + * @apiError (ERROR_CODE) ORDER_PAID 订单已支付 + * + */ +/** + * @api {PUT} /api/v1.0/gateway/partners/{partner_code}/card_orders/{order_id} 创建卡支付订单 + * @apiName CardOrder + * @apiGroup CardPayment + * @apiVersion 1.0.0 + * @apiDescription + * + * 卡支付即消费者输入银行卡信息进行下单的接口，接入卡支付需要额外的合规流程。
+ * 卡支付订单需要在商户页面引入js sdk并生成加密卡输入界面，消费者输入卡信息后通过回调将加密后的卡信息返回，商户请求时带上加密卡信息
+ * 卡支付下单无需后续消费者交互，直接可查询下单结果 + * + * @apiHeader Accept application/json + * @apiHeader Content-Type application/json + * @apiParam (PathVariable) {String} partner_code 必填，商户编码，由4位大写字母或数字构成 + * @apiParam (PathVariable) {String} order_id 必填，商户支付订单号，要求同一商户唯一 + * @apiUse Sign + * @apiParam (JSON) {String} description 必填，订单标题（最大长度128字符，超出自动截取） + * @apiParam (JSON) {int} price 必填，金额，单位为货币最小单位，例如使用100表示AUD1.00 + * @apiParam (JSON) {String=AUD,CNY} currency=AUD 币种代码，卡支付仅支持AUD下单 + * @apiParam (JSON) {String} notify_url 支付通知url，详见支付通知api，不填则不会推送支付通知 + * @apiParam (JSON) {String} operator 操作人员标识 + * @apiParam (JSON) {Boolean} domestic_only 默认为false，是否只允许本国卡。由于境内境外卡支付手续费差异巨大，可在此限制。 + * @apiParam (JSON) {Boolean} disable_credit_card 默认为false，如果希望限制消费者使用信用卡支付可传入true + * @apiParam (JSON) {String} key_id 必填，加密卡信息key id + * @apiParam (JSON) {String} card_info 必填，加密卡信息secret + * @apiParam (JSON) {JSON} customer 可选参数，提交消费者基本信息，可为charge back发生时提供依据 + * + * @apiParam (customer) {String} name 姓名，可选，如果未提供会自动使用card holder name + * @apiParam (customer) {String} postcode 邮编，可选，4位数字 + * @apiParam (customer) {String} address 地址，可选 + * @apiParam (customer) {String} city 城市，如Sydney + * @apiParam (customer) {String} state 州，可选，三位大写代码，如VIC + * @apiParam (customer) {String} country 国家，可选，ISO-3600-1标准收录的两位国家代码 + * + * @apiSuccess {String} return_code 执行结果 + * @apiSuccess {String} result_code SUCCESS表示创建订单成功，EXISTS表示订单已存在 + * @apiSuccess {String} partner_code 商户编码 + * @apiSuccess {String} channel 支付渠道 + * @apiSuccess {String} full_name 商户注册全名 + * @apiSuccess {String} partner_name 商户名称 + * @apiSuccess {String} order_id RoyalPay订单ID，同时也是支付渠道订单ID，最终支付成功的订单ID可能不同 + * @apiSuccess {String} partner_order_id 商户订单ID + * @apiSuccess {String} pay_url 跳转URL + * + * @apiUse GlobalError + * @apiError (ERROR_CODE) ORDER_MISMATCH 订单号与商户不匹配 + * @apiError (ERROR_CODE) ORDER_PAID 订单已支付 + * + */ +/** + * @api {GET} /api/v1.0/card_payment_view/partners/{partner_code}/orders/{order_id}/view 卡支付跳转页 + * @apiName CardInputView + * @apiDescription 必须先调用创建卡支付预订单接口再进行跳转。优先使用接口返回地址。 + * 建议在用户回调到对应页时通过后台查询订单状态接口确认订单的支付状态。 + * @apiVersion 1.0.0 + * @apiGroup CardPayment + * @apiParam (PathVariable) {String} partner_code 必填，商户编码，由4位大写字母或数字构成 + * @apiParam (PathVariable) {String} order_id 必填，商户支付订单号，要求已预先创建 + * @apiUse Sign + * @apiParam (QueryParam) {String} redirect 必填，支付成功后跳转页面，回调时会带上签名参数用于校验 + * + * @apiUse GlobalError + * @apiError (ERROR_CODE) ORDER_NOT_EXIST 订单不存在 + * @apiError (ERROR_CODE) ORDER_MISMATCH 订单号与商户不匹配 + */ /** * @api {PUT} /api/v1.0/jsapi_gateway/partners/{partner_code}/orders/{order_id} 创建JSAPI订单 * @apiName NewJSAPI @@ -1013,6 +1125,7 @@ * @apiError (ERROR_CODE) ORDER_MISMATCH 订单号与商户不匹配 * */ + /** * @api {PUT} /api/v1.0/customs/partners/{partner_code}/redeclare/report/{client_report_id} 重新提交报关单 * @apiName redeclare_report diff --git a/src/document/en/apidoc.json b/src/document/en/apidoc.json index 374c76566..4039388f3 100644 --- a/src/document/en/apidoc.json +++ b/src/document/en/apidoc.json @@ -22,6 +22,10 @@ "Miniprogram_Payment", "NewMobileH5Pay", "MobileH5Pay", + "CardPayment", + "CardPreOrder", + "CardInputView", + "CardOrder", "RetailPay", "RetailMicroPay", "RetailQRCode", diff --git a/src/document/en/apis.js b/src/document/en/apis.js index 351482eb1..f889409da 100644 --- a/src/document/en/apis.js +++ b/src/document/en/apis.js @@ -235,7 +235,119 @@ * @apiError (ERROR_CODE) ORDER_NOT_EXIST Order does not exist * @apiError (ERROR_CODE) ORDER_MISMATCH Order is not belong to this partner */ - +/** + * @api {PUT} /api/v1.0/gateway/partners/{partner_code}/pre_card_orders/{order_id} Create Card Pre Order + * @apiName CardPreOrder + * @apiGroup CardPayment + * @apiVersion 1.0.0 + * @apiDescription + * + * Card payment method is that customer provider their card information to finish payments. Enable card payment require addition compliance process.
+ * Card Pre Order is the way merchant create order first and then redirect to the page on royalpay to ask customer input card information and finish payment.
+ * Card Pre Order allows customer retry multiple times. So unless merchant call the closing api. Order will exists available until hit the expire time. + * + * @apiHeader Accept application/json + * @apiHeader Content-Type application/json + * @apiParam (PathVariable) {String} partner_code Required, Partner code + * @apiParam (PathVariable) {String} order_id Required, Partner order id + * @apiUse Sign + * @apiParam (JSON) {String} description Required, Order description + * @apiParam (JSON) {int} price Required, Price of the order. Use the base unit of the currency. + * @apiParam (JSON) {String=AUD,CNY} currency=AUD currency, Only AUD supported + * @apiParam (JSON) {String} notify_url System will call the notify url if provided when the payment succeeds + * @apiParam (JSON) {String} operator Note for the operator who created this order. + * @apiParam (JSON) {Boolean} domestic_only Default is false, Due to there is a huge rate difference between domestic cards and international cards. merchants can disable international cards + * @apiParam (JSON) {Boolean} disable_credit_card Default is false, if merchants want to limit customers not using credit cards. this parameter can be helpful + * @apiParam (JSON) {String} customer_id Optional, if merchants tokenized customer's card with a customer id, it can reference the card information and customers will only provide cvv2 code then. + * @apiParam (JSON) {JSON} customer Optional, json object, provide customer's basic information in case there were a charge back happened + * + * @apiParam (customer) {String} name customer's name. optional. if not provided system will use card holder name + * @apiParam (customer) {String} postcode optional + * @apiParam (customer) {String} address optional + * @apiParam (customer) {String} city optional,like Sydney + * @apiParam (customer) {String} state optional, 3-character state name. like NSW + * @apiParam (customer) {String} country optional, nation code, use 2-character code in ISO-3600-1 + * + * @apiSuccess {String} return_code Execution result + * @apiSuccess {String} result_code SUCCESS means order created successfully, EXISTS means order has already existed. + * @apiSuccess {String} partner_code Partner code + * @apiSuccess {String} channel Payment channel + * @apiSuccess {String} full_name Partner's full company name when registered + * @apiSuccess {String} partner_name Partner's name + * @apiSuccess {String} order_id Order id in RoyalPay, which is also payment channel(Wechat/Alipay) order id. + * @apiSuccess {String} partner_order_id Partner order id + * @apiSuccess {String} pay_url Payment page in RoyalPay. + * + * @apiUse GlobalError + * @apiError (ERROR_CODE) ORDER_MISMATCH Order is not belong to this partner + * @apiError (ERROR_CODE) ORDER_PAID Order has already been paid + * + */ +/** + * @api {PUT} /api/v1.0/gateway/partners/{partner_code}/card_orders/{order_id} 创建卡支付订单 + * @apiName CardOrder + * @apiGroup CardPayment + * @apiVersion 1.0.0 + * @apiDescription + * + * Card payment method is that customer provider their card information to finish payments. Enable card payment require addition compliance process.
+ * Card Order is the way merchant import our sdk in payment page and display a encrypting card input view. then collect the encrypted card info from callback and then pass them to royalpay to create order and finish payments
+ * Card Order api do not need customers reaction any more. merchants can check payment result directly after created order. + * + * @apiHeader Accept application/json + * @apiHeader Content-Type application/json + * @apiParam (PathVariable) {String} partner_code Required, Partner code + * @apiParam (PathVariable) {String} order_id Required, Partner order id + * @apiUse Sign + * @apiParam (JSON) {String} description Required, Order description + * @apiParam (JSON) {int} price Required, Price of the order. Use the base unit of the currency. + * @apiParam (JSON) {String=AUD,CNY} currency=AUD currency, Only AUD supported + * @apiParam (JSON) {String} notify_url System will call the notify url if provided when the payment succeeds + * @apiParam (JSON) {String} operator Note for the operator who created this order. + * @apiParam (JSON) {String} key_id Required, key_id of encrypted callback + * @apiParam (JSON) {String} card_info Required, secret of encrypted callback + * @apiParam (JSON) {Boolean} domestic_only Default is false, Due to there is a huge rate difference between domestic cards and international cards. merchants can disable international cards + * @apiParam (JSON) {Boolean} disable_credit_card Default is false, if merchants want to limit customers not using credit cards. this parameter can be helpful + * @apiParam (JSON) {JSON} customer Optional, json object, provide customer's basic information in case there were a charge back happened + * + * @apiParam (customer) {String} name customer's name. optional. if not provided system will use card holder name + * @apiParam (customer) {String} postcode optional + * @apiParam (customer) {String} address optional + * @apiParam (customer) {String} city optional,like Sydney + * @apiParam (customer) {String} state optional, 3-character state name. like NSW + * @apiParam (customer) {String} country optional, nation code, use 2-character code in ISO-3600-1 + * + * @apiSuccess {String} return_code Execution result + * @apiSuccess {String} result_code SUCCESS means order created successfully, EXISTS means order has already existed. + * @apiSuccess {String} partner_code Partner code + * @apiSuccess {String} channel Payment channel + * @apiSuccess {String} full_name Partner's full company name when registered + * @apiSuccess {String} partner_name Partner's name + * @apiSuccess {String} order_id Order id in RoyalPay, which is also payment channel(Wechat/Alipay) order id. + * @apiSuccess {String} partner_order_id Partner order id + * @apiSuccess {String} pay_url Payment page in RoyalPay. + * + * @apiUse GlobalError + * @apiError (ERROR_CODE) ORDER_MISMATCH Order is not belong to this partner + * @apiError (ERROR_CODE) ORDER_PAID Order has already been paid + * + */ +/** + * @api {GET} /api/v1.0/card_payment_view/partners/{partner_code}/orders/{order_id}/view 卡支付跳转页 + * @apiName CardInputView + * @apiDescription This page mush be called after payment order has been created. + * When jumping back to redirection URL, it is recommended to call the order query API to make sure the payment has succeeded. + * @apiVersion 1.0.0 + * @apiGroup CardPayment + * @apiParam (PathVariable) {String} partner_code Required, Partner code + * @apiParam (PathVariable) {String} order_id Required, Partner order id. It shall have already been created + * @apiUse Sign + * @apiParam (QueryParam) {String} redirect Required, Redirect url when payment succeeded. Contain sign parameters for validation. + * + * @apiUse GlobalError + * @apiError (ERROR_CODE) ORDER_NOT_EXIST Order does not exist + * @apiError (ERROR_CODE) ORDER_MISMATCH Order is not belong to this partner + */ /** * @api {PUT} /api/v1.0/jsapi_gateway/partners/{partner_code}/orders/{order_id} Create JSAPI Payment Order * @apiName NewJSAPI