OmiPay



Omipay Payment Technical DocumentationAuthorMax.WongCreate Date2018-7-20Versionv2.0.3Modify DateModifierDescription2018-9-26Max.WongAdd Wechat MiniProgram PaymentCatalog TOC \o "1-3" \h \z \u 1．Scenes of Payment PAGEREF _Toc525724731 \h 21.1In-Store Payment PAGEREF _Toc525724732 \h 2a)Merchant QR Code Payment PAGEREF _Toc525724733 \h 2b)POS Terminal Payment PAGEREF _Toc525724734 \h 21.2Online Payment PAGEREF _Toc525724735 \h 2a)Web Store Payment PAGEREF _Toc525724736 \h 2b)WeChat Store Payment PAGEREF _Toc525724737 \h 2c)Alipay Wap/Web Payment PAGEREF _Toc525724738 \h 2d)In-App Payment PAGEREF _Toc525724739 \h 2e)WeChat MiniProgram Payment PAGEREF _Toc525724740 \h 32．Rules PAGEREF _Toc525724741 \h 32.1Protocol Rules PAGEREF _Toc525724742 \h 32.2Parameter Rules PAGEREF _Toc525724743 \h 32.3Signature PAGEREF _Toc525724744 \h 32.4Error Codes PAGEREF _Toc525724745 \h 53．API List PAGEREF _Toc525724746 \h 52.1Get current exchange rate PAGEREF _Toc525724747 \h 52.2Make QRCode Order PAGEREF _Toc525724748 \h 62.3Make JSAPI Order PAGEREF _Toc525724749 \h 112.4Make Scan Order PAGEREF _Toc525724750 \h 162.5Make Online Order (Alipay Online) PAGEREF _Toc525724751 \h 192.6Make APP Order (Alipay Online) PAGEREF _Toc525724752 \h 212.7Make WeChat MiniProgram Order (WeChat) PAGEREF _Toc525724753 \h 222.8Query Order Status PAGEREF _Toc525724754 \h 252.9Payment Success Notification PAGEREF _Toc525724755 \h 272.10Refund PAGEREF _Toc525724756 \h 282.11Query Refund PAGEREF _Toc525724757 \h 30Scenes of PaymentOmipay supports the payment catalogs as below:In-Store PaymentMerchant QR Code PaymentMerchant could present a static QR Code to the customer. The customer should scan this QR Code via Alipay/WeChat App or any other app which integrates the browser on smartphone and then input the essential information on the payment page to complete the payment.Merchant could download the QR Code on Dashboard and print out it.Merchant QR Code Payment don’t need any API integration.POS Terminal PaymentThe customer shows their payment QRCode / barcode in Alipay/WeChat App, and then the merchant scans it via POS terminal to finish the payment. The introduction of this scene is Chapter REF _Ref519861887 \r \h \* MERGEFORMAT 3.4In other case, if the merchant’s POS terminal has a screen, then merchant can generate a dynamic QRCode and show it in the screen, customer scans it via Alipay/WeChat App to complete the payment.The introduction of this scene is Chapter REF _Ref521660496 \r \h \* MERGEFORMAT 3.3Online PaymentWeb Store PaymentWhen customer access the store web site on PC/tablet, merchant can generate a QRCode and present it out. Customer scan this QRCode via Alipay/WeChat App and then complete the payment directly.The introduction of this scene is Chapter REF _Ref521683293 \r \h \* MERGEFORMAT 3.3WeChat Store PaymentWhen customer access the web store in WeChat browser, merchant can get a payment URL from Omipay, and redirect the WeChat browser to this URL, then customer complete the payment in the payment page.The introduction of this scene is Chapter REF _Ref521684725 \r \h \* MERGEFORMAT 3.3Alipay Wap/Web Payment When customer access the store in smartphone web browser (e.g. Safari/Chrome), they should pay directly via Alipay by this way.The introduction of this scene is Chapter REF _Ref521684752 \r \h \* MERGEFORMAT 3.5In-App PaymentMerchant should integrate a SDK in your own Android/iOS app to let customer pay directly in it.The introduction of this scene is Chapter REF _Ref521684782 \r \h \* MERGEFORMAT 3.6WeChat MiniProgram PaymentIf you have a WeChat MiniProgram, you should call this API to finish the payment.The introduction of this scene is Chapter REF _Ref525724765 \r \h \* MERGEFORMAT 3.7Credit card PaymentIf you have a web store, and want to integrate the credit card checkout counter in it, you should see Chapter REF _Ref528678901 \r \h \* MERGEFORMAT 3.8RulesProtocol RulesTransafer ModeHTTPSSubmit ModePOST/GETReceive Data FormatJsonText EncodingUTF-8Sign AlgorithmMD5Data Sending FormatSending data as URL parameterHttp HeaderContentType=application/jsonExpiringSignature expires in 5 minutesParameter Rules 1）AmountAmount uses the smallest unit of transaction currency, must be integer value. e.g. amount 100 of currency AUD would be equivalent to A$1.00.2）CurrencyThe only currency type we support is AUD (Australian dollar).3）Time zoneSystem time zone is AEST (Australia East Standard Time). 4）Timestamp Convert current UTC time to milliseconds. 5）Nonce stringThe random string witch length in 10-32 characters，allows the characters in a-z | A-Z | 0-9. 6）Payment platformOmipay supports the payment platforms below:Platform nameThe value of parameter platform Wechat PayWECHATPAYAlipayALIPAY7） languageOmipay WebAPI supports multi-language. Set the Accept-Language value in HTTP　request header to handle it: LanguageThe value of parameter languageEnglishen-USSimplified Chinese (Default)zh-CNSignature Every request to Omipay Payment API must be signed, the sign algorithm is as below:1）ParametersThe parameters for verifying as below: NameTypeDescriptionm_numberStringMerchant number, can be found in merchant Dashboard()timestampLongTime stamp, refer to Timestamp in Parameter Rulesnonce_strStringRandom string, refer to Nonce string in Parameter Rulessecret_keyStringAPI Secret key of merchant, acquired from merchant Dashboard. This parameter is for private, don’t present in any public place.2）Generate signature① Concatenate all the parameters above like this:m_number&timestamp&nonce_str&secret_keyMake sure it’s in the correct order. ② Use the concatenated string to make a signature string with MD5 algorithm, and then turn it into uppercase.③ Put the signature string as a part of the query parameters, and then call the web api.e.g.:The parameters below:m_number123456timestamp1482812036067nonce_str313644f42ecd4758b5e23b80e86efdc4secret_key0af61531c6c04ac4ac910d0cd59e6238The concatenated string below:123456&1482812036067&313644f42ecd4758b5e23b80e86efdc4&0af61531c6c04ac4ac910d0cd59e6238Here are some sample codes of making the sign string:C#var originString = “123456&1482812036067&313644f42ecd4758b5e23b80e86efdc4&0af61531c6c04ac4ac910d0cd59e6238”;????var md5 = MD5.Create(); ???var bs = puteHash(Encoding.UTF8.GetBytes(originString)); ??var sb = new StringBuilder(); ??foreach (byte b in bs) ?{ ????sb.Append(b.ToString("x2")); ?} ??originString = sb.ToString().ToUpper();?PHP$originString = ‘123456&1482812036067&313644f42ecd4758b5e23b80e86efdc4&0af61531c6c04ac4ac910d0cd59e6238’;$sign = strtoupper(md5($originString));Get the signature string: sign=”516A3B52F9C8897F52239B19CD8A499”and then put it into the parameter string, we can get the parameter below:m_number=123456&timestamp=1482812036067&nonce_str=313644f42ecd4758b5e23b80e86efdc4&sign=8516A3B52F9C8897F52239B19CD8A499Use this string for signature verifying.Error CodesError CodeDescriptionMERCHANTNO_INVALIDThe merchant number is wrong, please check the corresponding merchant number from the merchant system.SIGN_ERRORSignature verification failed. Please check if the signature is correctSYSTEM_ERRORServer errorMERCHANTNO_DISABLEMerchant is disabledBRANCH_INVALIDBranch do not existAPI ListGet current exchange rateDescription：Get the current exchange rate of AUD to CNY, which is provided by WeChat/Alipay, refreshes in a day. This exchange rate is only for reference.API address: (except the sign verifying parameters, all the APIs are as the same.) FieldTypeExampleDescriptioncurrencyStringAUDThe currency code which follows the ISO-4217 standard. base_currencyStringCNYplatformStringWECHATPAYNot mandatory, defaults WECHATPAYSuccess returns: FieldTypeExampleDescriptionreturn_codeStringSUCCESSWhen execute succeed, returns SUCCESS,it shows the result of API execution.rateDecimal5.01540000Current exchange rateplatformStringWECHATPAYFail returns: FieldTypeExampleDescriptionreturn_codeStringFAILWhen execute failed, returns FAIL error_codeStringSYSTEM_ERRORCode of errorerror_msgStringSystem error.Description of errorError code list:Error CodeDescriptionCURRENCY_ERRORThe currency type error may be the unavailability of the exchange rate of the two currency types or the input error of the currency type.Request example:? m_number=123456&timestamp=1482812036067&nonce_str=313644f42ecd4758b5e23b80e86efdc4&sign=8516A3B52F9C8897F52239B19CD8A499&currency=AUD&base_currency=CNYSuccess returns example: { "return_code": "SUCCESS", "rate": 5.01540000}Fail returns example{ "return_code": "FAIL", "error_code": "SIGN_TIMEOUT", "error_msg": "Sign time out."}Make QRCode OrderDescription:QRCode order suits for the scene of PC web store payment. Merchant can call this API to get a string for payment, and then show this string to customer as a QRCode; Customer would scan this QRCode with WeChat/Alipay to finish the pay.Sequence diagram:API address: simple order information.currencyStringAUDCurrency code of the order.amountint100Order amount in the base unit of the currency of order. Refers to section 1.2.e.g. if currency = AUD, then 100 means A$1.00notify_urlStringNotification URL for transaction success. When this order is pay succeed, will send a notification to such URL. Refers to section 2.6. out_order_noStringOut order number. The notification data of transaction would include this field. So, it best be unique, in order to identify the order.platformStringWECHATPAYpayment platform of this order.o_numberString01number of the transaction organization.Success returns: FieldTypeExampleDescriptionreturn_codeStringSUCCESSSUCCESSorder_noStringOmipay order number, 32 characters length. QrcodeStringString for QRCode. Pay_urlStringThe url of common payment page. When order is created, may redirect to this url to show the payment QRCode.* Access this page is also needs signing, the sign algorithm is same to other methods.Fail returns: FieldTypeExampleDescriptionreturn_codeStringFAILFAILerror_codeStringSYSTEM_ERRORCode of errorerror_msgStringSystem error.Description of errorError Code list:Error CodeDescriptionWEBSTORE_NOT_EXISTSThe merchant did not register an online store.The error will occur if the merchant does not register with Omipay.AMOUNT_INVALIDThe amount is incorrect.This error will be prompted when the amount is greater than the maximum amount of a single transaction allowed by the payment platform, or the amount converted by the exchange rate is less than the minimum amount paid by the payment platformCURRENCY_ERRORThe currency type error may be the unavailability of the exchange rate of the two currency types or the input error of the currency typeOUT_TRANSACTION_PAIDOut order number has been paidTRANSACTION_TIMEOUTOrder has expiredRequest example: ? M_number=123456&timestamp=1482812036067&nonce_str=313644f42ecd4758b5e23b80e86efdc4&sign=8516A3B52F9C8897F52239B19CD8A499&order_name=Test_Order&amount=100&notify_url= comments: The flow of QRCode payment:Merchant create order in Web or PC Online-Store;Call Omipay MakeQROrder API; Generate QRCode with the qrcode string of API returns, and then show it to customer in application interface; OR: Redirect to pay_url and show the QRCode.Customer scan this QRCode with WeChat/Alipay APP on mobile phone.Customer finish the payment.Omipay send transaction notification data to merchant.Success returns example: { “return_code”: “SUCCESS”, “order_no”: “bc112874260946a2af2b7107825e6ce2”, “qrcode” : “………………. “}Fail returns example: { “return_code”: “FAIL”, “error_code”: “SIGN_TIMEOUOT”, “error_msg”: “Sign timeout.”}Description of payment page:When API returns, may lead the browser redirect to the pay_url address. Which page shows the information of order and the payment QRCode. Customer scans this QRCode with Alipay/Wechatpay app in mobile phone to finish the transaction. When payment is done, browser would redirect to the redirect_url address which in the call parameter.For accessing the pay_url, the following parameters are required. FieldTypeExampleDescriptionm_numberStringtimestampString1482812036067Time stamp, refer to Timestamp in Parameter RulesnoncestringStringRandom string, refer to Nonce string in Parameter RulessignStringSign stringredirect_urlStringBrowser will redirect to such url when payment done.Make JSAPI Order Description:JSAPI order suits for the scenes below:WeChat web browser based payment. Merchant could call this API to get a URL for payment, and then lead customer to access this URL to pay. Common pay QRCode for transaction. Merchant could use the pay_url generate a QRCode, and show it to customer. Customer could scan this code with either Wechat or Alipay client app on mobile phone to pay.Sequence diagram:API address: : ParameterTypeExampleDescriptionorder_nameStringTEST_ORDERThe simple order information.CurrencyStringAUDCurrency code of the order.Amountint100Order amount in the base unit of the currency of order. Refers to section 1.2.e.g. if currency = AUD, then 100 means A$1.00notify_urlStringNotification URL for transaction success. When this order is pay succeed, will send a notification to such URL. Refers to section 2.6. redirect_urlStringRedirecting URL for transaction success. When this order is pay succeed, web browser will auto redirect to such URL.Out_order_noStringOut order number. The notification data of transaction would include this field. So, it best be unique, in order to identify the order.direct_payInt1Not mandatory, if this parameter transferred, the order will be paid directly when the pay_url is open.Show_pc_pay_urlInt1Not mandatory, if this parameter transferred, API response object would include a parameter that shows a PC payment page URL . You can redirect to this URL and show the order OQCode to customer.See Description of payment page section to get more details.o_numberString01Not mandatory, number of transaction organization.pos_noStringNot mandatory, POS device number.Success returns: FieldTypeExampleDescriptionreturn_codeStringSUCCESSSUCCESSorder_noStringOmipay order number, 32 characters length. pay_urlStringURL for payment. Merchant should lead user to access this URL. Fail returns: FieldTypeExampleDescriptionreturn_codeStringFAILFAILerror_codeStringSYSTEM_ERRORCode of errorerror_msgStringSystem errorDescription of errorError Code list: Error CodeDescriptionWEBSTORE_NOT_EXISTSThe merchant did not register an online store.The error will occur if the merchant does not register with Omipay.AMOUNT_INVALIDThe amount is incorrect.This error will be prompted when the amount is greater than the maximum amount of a single transaction allowed by the payment platform, or the amount converted by the exchange rate is less than the minimum amount paid by the payment platformCURRENCY_ERRORThe currency type error may be the unavailability of the exchange rate of the two currency types or the input error of the currency typeOUT_TRANSACTION_PAIDOut order number has been paidTRANSACTION_TIMEOUTOrder has expiredPOS_NOT_REGISTEREDMerchant POS terminal is not registeredPOS_NOT_BINDThe Pos machine is not tied to the storeRequest example: ? m_number=123456&timestamp=1482812036067&nonce_str=313644f42ecd4758b5e23b80e86efdc4&sign=8516A3B52F9C8897F52239B19CD8A499&order_name=TEST_ORDER&redirect_url= returns example: { "return_code": "SUCCESS", "order_no": "bc112874260946a2af2b7107825e6ce2", "pay_url" : "………………. "}Fail returns example: { "return_code": "FAIL", "error_code": "SIGN_TIMEOUOT", "error_msg": "Sign timeout."}Additional:JSAPI order request should includes redirect_url parameter. And when customer finished the payment, mobile browser would redirect to such URL.Description of payment page:If the request parameter includes the parameter show_pc_pay_url, and its value is 1 (show_pc_pay_url = 1), then the API response data would contain a property as pc_pay_url, which is the pay ur l for PC browser. Merchant may lead the PC browser redirect to such address, which page show the information of order an the payment QRCode. Customer scans this QRCode with Alipay/Wechatpay app in mobile phone to finish the transaction. When payment is done, browser would redirect to the redirect_url address which in the call parameter.The PC payment page is like:For accessing the pc_pay_url, the following parameters are required. FieldTypeExampleDescriptionm_numberStringtimestampString1482812036067Time stamp, refer to Timestamp in Parameter RulesnoncestringStringRandom string, refer to Nonce string in Parameter RulessignStringSign stringredirect_urlStringBrowser will redirect to such url when payment done.Make Scan Order Description:Scan order is suits the scene of local payment. Customer shows the Payment code in WeChat Wallet/Alipay client, merchant scans the code by POS device, AND then call API to create order.API address： diagram:Parameters: ParameterTypeExampleDescriptionorder_nameStringTEST_ORDERThe simple order information.currencyStringAUDCurrency code of the order.amountint100Order amount in the base unit of the currency of order. Refers to section 1.2.e.g. if currency = AUD, then 100 means A$1.00notify_urlStringNotification URL for transaction success. When this order is pay succeed, will send a notification to such URL. Refers to section 2.6.qrcodeStringCustomer’s payment QRCode. pos_noStringPOS Device number.out_order_noStringOut order number. The notification data of transaction would include this field. So, it best be unique, in order to identify the order.Success returns: FieldTypeExampleDescriptionreturn_codeStringSUCCESSSUCCESS：Pay succeed order_noStringOmipay order number, 32 characters length.out_order_noStringOut order number.order_timeStringOrder pay time, in format of yyyyMMddHHmmssFail returns:FieldTypeExampleDescriptionreturn_codeStringFAILFAILerror_codeStringSYSTEM_ERRORCode of errorerror_msgStringServer errorDescription of errororder_noStringIf error_code = “USERPAYING”, then returns this field. Refers to Addition comments.Error Code list:Error CodeDescriptionCURRENCY_ERRORThe currency type error may be the unavailability of the exchange rate of the two currency types or the input error of the currency typeAMOUNT_INVALIDThe amount is incorrect.This error will be prompted when the amount is greater than the maximum amount of a single transaction allowed by the payment platform, or the amount converted by the exchange rate is less than the minimum amount paid by the payment platformUSERPAYINGThe user is payingORDER_PAIDThe payment order has been paidPOS_NOT_REGISTEREDMerchant POS terminal is not registeredPOS_NOT_BINDThe Pos terminal is not tied to the branchCARD_NOT_SUPPORTType of card not supportedORDER_CLOSEDOrder closedOUT_TRANSACTION_PAIDOut order number has been paidTRANSACTION_TIMEOUTOrder has expiredRequest example: ? m_number=123456&timestamp=1482812036067&nonce_str=313644f42ecd4758b5e23b80e86efdc4&sign=8516A3B52F9C8897F52239B19CD8A499&order_name=Test_Order&amount=100&&notify_url= comments：The flow of Scan payment:Merchant create the order in POS System, and show the amount of such order to customer;Customer show the Payment QRCode of WeChat Wallet; Merchant scan the QRCode with POS Device, and call MakeScanOrder API to create payment order.Omipay server solves the request, meanwhile, merchant waits for the result of order.If Omipay returns the SUCCESS code, the flow finish; else if return_code is FAIL and error_code is not USERPAYING, the flow fails; else into step 6); The return_code is USERPAYING means customer had to input payment password. （Whether to input the password depends on the security policy of WeChat Payment/Alipay）If customer had to input password, merchant should to hold this order and waiting for the response from Omipay server. When customer finished the payment, Omipay would call notify_url and send the payment information. Merchant could also call QueryOrder API to get the status of payment transaction. Make Online Order (Alipay Online)Description:Online order is suits the scene of pc(web eg. Chrome/IE)/mobile(wap eg. Safari) browser payment.API address：: ParameterTypeExampleDescriptionorder_nameStringTEST_ORDERThe simple order information.currencyStringAUDCurrency code of the order.amountint100Order amount in the base unit of the currency of order. Refers to section 1.2.e.g. if currency = AUD, then 100 means A$1.00out_order_noStringOut order number. The notification data of transaction would include this field. So, it best be unique, in order to identify the order.notify_urlStringNotification URL for transaction success. When this order is pay succeed, will send a notification to such URL. Refers to section 2.6.return_urlStringNot mandatory, when transaction finished, browser will redirect to this URL synchronized.typeStringweb/wapPC browser: webmobile browser: wapo_numberString01Not mandatory, number of transaction organization.Success returns: FieldTypeExampleDescriptionreturn_codeStringSUCCESSSUCCESS：Pay succeed order_noStringOmipay order number, 32 characters length.pay_urlStringURL for payment. Merchant should lead user to access this URL. Fail returns:FieldTypeExampleDescriptionreturn_codeStringFAILFAILerror_codeStringSYSTEM_ERRORCode of errorerror_msgStringServer errorDescription of errorError Code list:Error CodeDescriptionWEBSTORE_NOT_EXISTSThe merchant did not register an online store.The error will occur if the merchant does not register with Omipay.AMOUNT_INVALIDThe amount is incorrect.This error will be prompted when the amount is greater than the maximum amount of a single transaction allowed by the payment platform, or the amount converted by the exchange rate is less than the minimum amount paid by the payment platformCURRENCY_ERRORThe currency type error may be the unavailability of the exchange rate of the two currency types or the input error of the currency typeMake APP OrderDescription:App order is suits the scene of iOS/Android App payment.API address：: ParameterTypeExampleDescriptionorder_nameStringTEST_ORDERThe simple order information.currencyStringAUDCurrency code of the order.amountint100Order amount in the base unit of the currency of order. Refers to section 1.2.e.g. if currency = AUD, then 100 means A$1.00notify_urlStringNotification URL for transaction success. When this order is pay succeed, will send a notification to such URL. Refers to section 2.6.out_order_noStringOut order number. The notification data of transaction would include this field. So, it best be unique, in order to identify the order.platformStringALIPAYONLINEALIPAYONLINE/WECHATPAYo_numberString01Not mandatory, number of transaction organization.app_idStringwxc571a1u199z0qc240In some payment platform, such as WechatPay, it identifies the app.Success returns: FieldTypeExampleDescriptionreturn_codeStringSUCCESSSUCCESS：Pay succeed order_noStringOmipay order number, 32 characters length.order_stringStringPayment string for Alipay APP calling.Fail returns:FieldTypeExampleDescriptionreturn_codeStringFAILFAILerror_codeStringSYSTEM_ERRORCode of errorerror_msgStringServer errorDescription of errorError Code list:Error CodeDescriptionWEBSTORE_NOT_EXISTSThe merchant did not register an online store.The error will occur if the merchant does not register with Omipay.AMOUNT_INVALIDThe amount is incorrect.This error will be prompted when the amount is greater than the maximum amount of a single transaction allowed by the payment platform, or the amount converted by the exchange rate is less than the minimum amount paid by the payment platformCURRENCY_ERRORThe currency type error may be the unavailability of the exchange rate of the two currency types or the input error of the currency typeMobile App develop reference:iOS:WECHAT: WeChat MiniProgram Order (WeChat)Description:If merchant have a WeChat MiniProgram, then you should call this API to finish the payment.* The introduction of WeChat MiniProgram, you should see here: Diagram:API Address:: ParameterTypeExampleDescriptionorder_nameStringTEST_ORDERThe simple order information.currencyStringAUDCurrency code of the order.amountint100Order amount in the base unit of the currency of order. Refers to section 1.2.e.g. if currency = AUD, then 100 means A$1.00notify_urlStringNotification URL for transaction success. When this order is pay succeed, will send a notification to such URL. Refers to section 2.6. out_order_noStringOut order number. The notification data of transaction would include this field. So, it best be unique, in order to identify the order.o_numberString01Not mandatory, number of transaction organization.app_idStringwx20oq811f9qThe AppId of WeChat MiniProgramcustomer_idStringo89hJw3wUbThe customer OpenId obtained from WeChat.Success returns:FieldTypeExampleDescriptionreturn_codeStringSUCCESSSUCCESSorder_noStringOmipay order number, 32 characters length. timeStampStringNecessary field to call WeChat Payment in frontend.nonceStrStringNecessary field to call WeChat Payment in frontend.PackageStringNecessary field to call WeChat Payment in frontend.SignTypeStringNecessary field to call WeChat Payment in frontend.paySignintNecessary field to call WeChat Payment in frontend.Fail returns: FieldTypeExampleDescriptionreturn_codeStringFAILFAILerror_codeStringSYSTEM_ERRORCode of errorerror_msgStringsystem errorDescription of errorError code list: Error CodeDescriptionPARAMETER_INVALIDInvalid parameters.SIGN_TIMEOUTTime stamp expires.MERCHANTNO_INVALIDMerchant number is invalid.SIGN_ERRORSignature check failed. SYSTEM_ERRORSystem unhandled error.PERMISSION_ERRORPermission error, Occurs when the order number is not belongs to current merchant.Request example: flow of integrating Omipay in you WeChat MiniProgram:1) Merchant should apply a MiniProgram in WeChat Public Platform(). The owner must be the same to the institution of merchant.2) Finish the WeChat certification and obtain the AppId of your MiniProgram.3) Give the AppId to Omipay.4) Start your technical integration flow. The example code of call Payment in MiniProgram front-end:wx.requestPayment({'timeStamp':?'data.timeStamp','nonceStr':?'data.nonceStr','package':?'data.package','signType':?'data.signType','paySign':?'data.paySign','success':function(res){},'fail':function(res){},'complete':function(res){}})Credit Card Checkout CounterDescription:Merchant could integrate checkout counter in the web store, and then use the Credit Card payment easily.Sequence diagram:The Instructions of integrationPut this code in the web page:<script type="text/javascript" class="omipay-button"src=""data-action=""data-key="ef673278b24411e88a5600163e020c69"data-amount="100"data-outOrderNo=""data-lang="cn"data-currency="AUD"data-store="01"data-redirectUrl=""data-text="OmiPay"></script>The description of the parameters:FieldTypeExampleDesctiptiondata-actionstring server url which response the data post.data-keystringasdkahskdhaksdhPublic Key of merchant, it should be obtained from Dashboarddata-amountint100Order amount in the base unit of the currency of order. Refers to section 1.2.e.g. if currency = AUD, then 100 means A$1.00data-storestring01Not mandatory, number of transaction organization.data-redirectUrlString mandatory, browser will redirect to such url when payment done.data-outOrderNoStringAsdalskjdalsjdNot mandatory, Out order number. The notification data of transaction would include this field. So, it best be unique, in order to identify the order.data-langInt1/0Not mandatory, The language of data-currencyStringAUDNot mandatory, the currency number of order. (AUD only)data-textStringOmiPayNot mandatory, the caption text of “Pay” button. In default, displays “OmiPay”Or else, you could use Javasctipt code to create the object dynamicly:<button id="customButton">OmiPay</button><script type="text/javascript" src=""></script><script>window.onload = function(){var handler = new OmiCheckout({"data": {"key": "ef673278b24411e88a5600163e020c69", "store": "01", "redirect_url": "", "action": "", },"successBack": function(res){console.log("successBack", res);},"errorBack": function(res){console.log("errorBack",res);}});$("#customButton").on({'click': function(){handler.open({amount: 20,currency: "AUD"});}})}</script>The description of the parameters:FieldTypeExampleDesctiptionactionstring server URL which responses the data post.keystringasdkahskdhaksdhPublic Key of merchant, it should be obtained from Dashboardamountint100Order amount in the base unit of the currency of order. Refers to section 1.2.e.g. if currency = AUD, then 100 means A$1.00storestring01Not mandatory, number of transaction organization.redirect_urlString mandatory, browser will redirect to such url when payment done.out_order_noStringAsdalskjdalsjdNot mandatory, Out order number. The notification data of transaction would include this field. So, it best be unique, in order to identify the order.langStringen/cnNot mandatory, The language of the checkout form. In default, the form would use the system language.currencyStringAUDNot mandatory, the currency number of order. (AUD only)textStringOmiPayNot mandatory, the caption text of “Pay” button. In default, displays “OmiPay”When payment process over, the function “successBack” would be called. And the parameter “res” contains these parameters: FieldTypeExampleDesctiptionstatusStringPAIDthe status code of the payment.TIMEOUT: the order is timeout;PAYING: the order is under checking;PAID: the order is successfully paid;CANCEL: payment failed, and the order is cancelled;FAIL: payment failed.dataJSONThe data is a JSON object, and it contains these parameters:nametypedescriptionorder_amountdecimalAmount in order_currency.order_currencyStringThe currency number of order.pay_amountdecimalAmount in pay_currencypay_currencyStringThe currency number of the credit card which paid in this order.fee_amountdecimalorder_amount * surcharge_rateexchange_ratedecimalThe exchange rate of pay_currency/ order_currencytransaction_numberStringOmipay transaction numberbranch_nameStringThe name of transaction branchout_order_noStringWhen merchant’s web server received the request of payment, it should call the ConfirmCheckout web api to finish the payment process. 2.1) API address:) Parameters:ParameterTypeExampleDescriptiontoken_idStringtoken_36630b33fa2a418d8411bb725The unique id of this payment request, it generated by OMIPAY server. 2.3) Success returns:FieldTypeExampleDescriptionreturn_codeStringSUCCESSSUCCESS result_codeStringPAIDorder statusout_order_noStringThe out order no value which is sent by merchant when calls pay api. 2.4) Fail returns:FieldTypeExampleDescriptionreturn_codeStringFAILFAILerror_codeStringSYSTEM_ERRORCode of errorerror_msgStringsystem errorDescription of error2.5) Error Code list:Error CodeDescriptionEXPIRED_TOKENThe token of payment is expired.2.6) Request example:? nonce_str=uXWTAw0g3q5HOHjdZW4opDbfp1a7dBOI&m_number=000034&platform=CARDPAY&notify_url=&timestamp=1513242617000&sign=1266C828F67A1C5BD0DC0203405D4480&token_id=token_36630b33fa2a418d8411bb725Query Order Status Description: Merchant could call this API to get the status of order.API address: : ParameterTypeExampleDescriptionorder_noStringOmipay Order number languageStringENSuccess returns:FieldTypeExampleDescriptionreturn_codeStringSUCCESSSUCCESS result_codeStringPAIDorder statusout_order_noStringThe out order no value which is sent by merchant when calls pay api. currencyStringAUDorder currency code, which is defined in ISO?4217 standard.Currently, it always be AUD.amountint100amount in order currency type.(AUD)order_timeStringOrder create time, in format of yyyyMMddHHmmsspay_timeStringOrder pay time, in format of yyyyMMddHHmmss;If order is not payed, the field value is empty string. exchange_rateintExchange rete of order currency type(AUD) to CNY; 10^8 times of real exchange rate value.pay_currencyStringCNYThe currency no which customer actually y_amountintamount in pay_currency.Fail returns: FieldTypeExampleDescriptionreturn_codeStringFAILFAILerror_codeStringSYSTEM_ERRORCode of errorerror_msgStringsystem errorDescription of errorError code list: Error CodeDescriptionPARAMETER_INVALIDInvalid parameters.SIGN_TIMEOUTTime stamp expires.MERCHANTNO_INVALIDMerchant number is invalid.SIGN_ERRORSignature check failed. SYSTEM_ERRORSystem unhandled error.PERMISSION_ERRORPermission error, Occurs when the order number is not belongs to current merchant.Request example: ? m_number=123456&timestamp=1482812036067&nonce_str=313644f42ecd4758b5e23b80e86efdc4&sign=8516A3B52F9C8897F52239B19CD8A499&order_no=bc112874260946a2af2b7107825e6ce2&language=ENSuccess returns example: { "return_code": "SUCCESS", "result_code": "PAYED", "currency": "AUD", "total_amount": 100, "order_time": "20161227105530", "pay_time": "20161227105602", "exchange_rate": 650000000, "cny_amount": 650}Fail returns example: { "return_code": "FAIL", "error_code": "SIGN_TIMEOUOT", "error_msg": "Sign timeout."}Order status list: StatusDescriptionREADYOrder is created, but not payed.PAYINGCustomer is now paying. PAIDCustomer is already payed.SETTLEDOrder is settled. (Settled by Omipay)CANCELLEDOrder is cancelled.FAILEDCustomer pay failed.Payment Success Notification Description:If the order is created with notify_url parameter, Omipay will send a request to this URL when payment success. This request would retries in 3 times unless received correct response.Request Rules: Text EncodingUTF8Http HeaderContent-Type=application/jsonData Sending FormatData is transferred in request body, in JSON format.Returns Data Typeapplication/jsonParameters: ParameterTypeExampleDescriptionreturn_codeStringSUCCESSreturn SUCCESS when pay succeed.nonce_strStringRandom nonce string.timestampLongTime stampsignStringSignature string.order_noStringOmipay order no.out_order_noStringOut order no.currencyStringAUDorder currency code, which is defined in ISO?4217 standard.Currently, it always be AUD.amountint100amount in order currency type.(AUD)order_timeStringOrder create time, in format of yyyyMMddHHmmsspay_timeStringOrder pay time, in format of yyyyMMddHHmmss;If order is not payed, the field value is empty string. exchange_rateintExchange rete of order currency type(AUD) to CNY; 10^8 times of real exchange rate value.pay_currencyStringCNYThe currency no which customer actually y_amountintamount in pay_currency.Notice: Merchant has to verify the sign information when receives the notification to prevent of the third-party attack. Merchant returns: FieldTypeExampleDescriptionreturn_codeStringSUCCESSMust be SUCCESS.Refund Description:Merchant could call this method to refund.API address: : ParameterTypeExampleDescriptionorder_noStringOmipay Order number which is going to be refunded.out_refund_noStringOut refund no.amountIntRefund amount in order currency.languageStringENSuccess returns:FieldTypeExampleDescriptionreturn_codeStringSUCCESSSUCCESSrefund_noStringOmipay refund bill No.currencyStringAUDCurrency No of refund.amountint100Refund amountrefund_timeStringRefund timeFail returns: FieldTypeExampleDescriptionreturn_codeStringFAILFAILerror_codeStringSYSTEM_ERRORCode of errorerror_msgStringServer errorDescription of errorError code list:Error CodeDescriptionAMOUNT_OVER_LIMITThe amount exceeds the refund limitPERMISSION_ERRORPermission error occurred when the refund order number does not belong to the merchant.Request example:? m_number=123456&timestamp=1482812036067&nonce_str=313644f42ecd4758b5e23b80e86efdc4&sign=8516A3B52F9C8897F52239B19CD8A499&order_no=bc112874260946a2af2b7107825e6ce2&out_refund_no=xxxxxxx&amount=100&language=ENSuccess returns:{ "return_code": "SUCCESS", "refund_no ": "ADDFGHJKL", "currency": "AUD", "amount": 100, "refund_time": "20161227105530" }Fail returns:{ "return_code": "FAIL", "error_code": "SIGN_TIMEOUOT", "error_msg": "Sign timeout."}Additional comments：Refund is based on transaction, each refund bill has hooked with a specific transaction. An order could be refunded multiple times. The total amount of such refunds shouldn’t be more than order amount. The api returns SUCCESS just means refund request is sent to payment platform, and the platform is accepted the request, it doesn’t means the refund flow finished. Query RefundDescription：Merchant should call this api to get the status of specific refund.API address： no of Omipay.languageStringENSuccess returns:ParameterTypeExampleDescriptionreturn_codeStringSUCCESSSUCCESSresult_codeStringCLOSEDstatus of refund.out_refund_noStringOut order No.currencyStringAUDCurrency No of refundamountint100amount in order currency type.refund_timeStringRefund create date. In formats of yyyyMMddHHmmsssuccess_timeStringActually refund time. In formats of yyyyMMddHHmmss; If refund status is not CLOSED, then returns empty string.Fail returns: FieldTypeExampleDescriptionreturn_codeStringFAILFAILerror_codeStringSYSTEM_ERRORCode of errorerror_msgStringServer errorDescription of errorError code list:Error codeDescriptionPARAMETER_INVALIDInvalid parameters.SIGN_TIMEOUTTime stamp expires.MERCHANTNO_INVALIDMerchant number is invalid.SIGN_ERRORSignature check failed. SYSTEM_ERRORSystem unhandled error.PERMISSION_ERRORPermission error, Occurs when the order number is not belongs to current merchant.REFUND_NO_ERRORRefund No is not correct.Request example:? m_number=123456&timestamp=1482812036067&nonce_str=313644f42ecd4758b5e23b80e86efdc4&sign=8516A3B52F9C8897F52239B19CD8A499&refund_no=bc112874260946a2af2b7107825e6ce2&language=ENSuccess returns:{ "return_code": "SUCCESS", "result_code": "CLOSED", "currency": "AUD", "amount": 100, "refund_time": "20161227105530", "success_time": "20161227105602"}Fail returns:{ "return_code": "FAIL", "error_code": "SIGN_TIMEOUOT", "error_msg": "Sign time out"}Refund status list:StatusDescriptionAppliedCustomer is applied the refund request.MerchantConfirmedMerchant accepted the refund request, and submitted to payment anizationConfirmedPayment platform is confirmed anizationPaybackPayment platform is already refunded.ClosedRefund flow is finished, flow closed.MerchantRejectedMerchant rejected the refund request.TimeoutClosedThe refund request is over the time limit for refunding of this anizationFailedPayment platform operation failed.CustomerCancelledCustomer cancelled refund request. ................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download