API Documentation
The parameter "notify_url" in Payment APIs, aka Payment Notification URL, is used to receive payment result notification from payment system to merchant’s system after payment is sucecssful.
Payment result notifications may be sent from the payment system to the Merchant’s backend multiple times, a single payment result might be notified to the Merchant’s backend multiple times. For this reason, the Merchant’s system must be able to handle duplicate notifications properly.
After receiving payment result notifications from Merchant’s backend, merchant’s system should process the status of their order. Merchant’s system should check the received "out_trade_no" and "total_fee" from payment result notification with Merchant’s order transaction. If they are all matched, the Merchant’s system should update the order’s status in their system and return the string "success" (case insensitive) to the payment system.
Otherwise, the payment system will continue to send payment result notifications within three hours if the payment system do not receive merchant’s response with the string "success".
The payment system sends payment result in form of XML content by HTTP POST to merchant’s defined in "notify_url".
| Name | ID | Required | Type | Description |
| API Version | version | Yes | String(8) | Default value: 1.0 |
| Charset | charset | Yes | String(8) | Default value: UTF-8 |
| Signature Type | sign_type | Yes | String(8) | Default value: MD5 |
| Return Status Code | status | Yes | String(16) | This parameters indicates whether the API call is successful or not but this doesn't indicate to have a successful transaction. If the value is 0, then it indicates sucecssful. Otherwise, it indicates failure. |
| Return Message | message | No | String(128) | The description of the Return Status Code if the value of parameter "status" is not 0. |
| The below parameters will be returned if the value of the parameter "status" is 0. | ||||
| Service Result | result_code | Yes | String(16) | If the value is 0, then it indicates sucecssful. Otherwise, it indicates failure. |
| Merchant ID (MID) | mch_id | Yes | String(32) | Specifies Merchant ID assigned by iOnline Pay |
| Device ID | device_info | No | String(32) | Specifies the ID of the terminal device with from which the Merchant submitted their order |
| Random String | nonce_str | Yes | String(32) | 32 characters or fewer. |
| Error Code | err_code | No | String(32) | Error code |
| Error Message | err_msg | No | String (128) | The description of error code |
| Signature | sign | Yes | String(32) | Signature Hash. For more information, see "Security Specification" |
| The below parameters will be returned if the value of the both parameters "status" and "result_code" are 0. | ||||
| User Tag | openid | No | String(128) | Unique User ID of Service Provider App ID in WeChat |
| Trade Type | trade_type | Yes | String(32) | ionline.pay.weixin.native.intl |
| Does user follow Offical Account? | is_subscribe | No | String(1) | This indicates whether user has followed Offical Account of Service Provider or not.
Y = Followed N = Not yet follow |
| Payment Result | pay_result | Yes | Int |
Indicates whether the payment is successful or not. 0 = success 1= failure |
| Payment Information | pay_info | No | String(64) | The value is empty if the payment result is successful. |
| Platform Order Number | transaction_id | Yes | String(32) | Unique transaction ID in the payment system. |
| Payment Channel Order Number | out_transaction_id | Yes | String(32) | Unique transaction ID in the payment gateway system. |
| Does user follow Merchant’s Offical Account? | sub_is_subscribe | No | String(1) | This indicates whether user has followed Merchant’s Offical Account or not. Y = Followed N = Not yet follow |
| Sub Official Account / Mini Program ID | sub_appid | No | String |
Proivde WeChat Offical Account ID (App ID) when requesting Offical Account Payment. Proivde WeChat Mini Program ID (App ID) when requesting Mini Program Payment. |
| User Tag | sub_openid | No | String(128) | Unique ID to identify an user in WeChat Offical Account / Mini Program |
| Order Number | out_trade_no | Yes | String(32) | out_trade_no is an internal order number within the Vendor’s system. |
| Total order amount | total_fee | Yes | Int | Specifies the total order amount. The units are expressed in cents as integers. The default currency is HKD. |
| Coupon Amount | coupon_fee | No | Int | The amount of coupon used by payer in this transaction. |
| Currency Type | fee_type | Yes | String(8) | ISO-4217 standard compliant and be described by three characters based code. |
| Additional Data | attach | No | String(127) | Allow merchants an additional field to be returned in the payment notification after submitting a payment to the Query Order API |
| Payment Completion Time | time_end | Yes | String(14) | Specifies the payment completion time in the format yyyyMMddHHmmss, such as 20170520094130 for May 20, 2017 09:41:30 (GMT+8). |
The payment system sends payment result in form of XML content by HTTP POST to merchant’s defined in "notify_url". After Merchant’s system process the transaction, it should return the plaintext value to indicate the status of transaction process as below:
| Return Result | Description |
| success | Merchant’s system processes transaction successfully. The payment system wouldn’t continue to send payment result notification afterward. |
| fail or other string | Merchant’s system fails to process transaction. The payment system will continue to send payment result notification. |