Rules

Protocol Rules

Parameter Rules

1）Amount

Amount 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）Currency

The only currency type we support is AUD (Australian dollar).

3）Time zone

System time zone is EST (East Standard Time).

4）Timestamp

Convert current UTC time to milliseconds.

5）Nonce string

The random string witch length in 10-32 characters，allows the characters in a-z |A-Z | 0-9.

6）Payment platform

Omipay supports the payment platforms below:

Platform name	The value of parameter platform
Wechat Pay	WECHATPAY
Alipay	ALIPAY

7） language

Omipay WebAPI supports the languages below:

Language	The value of parameter language
English	EN
Simplified Chinese (Default)	CHS

Signature verification

1）Parameters

The parameters for verifying as below:

Name	Type	Description
m_number	String	Merchant number, can be found in merchant backgroundsystem.
timestamp	Long	Time stamp, refer to Timestamp in Parameter Rules
nonce_str	String	Random string, refer to Nonce string in Parameter Rules
secret_key	String	API Secret key of merchant, acquired from merchant background system. This parameter is for private, don’t let it shown in any public place.

2）Generate signature

① Concatenate all the parameters above like this:

m_number&timestamp&nonce_str&secret_key

Make 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_number	123456
timestamp	1482812036067
nonce_str	313644f42ecd4758b5e23b80e86efdc4
secret_key	0af61531c6c04ac4ac910d0cd59e6238

The concatenated string below：

123456&1482812036067&313644f42ecd4758b5e23b80e86efdc4&0af61531c6c04ac4ac910d0cd59e6238

The code of making sign string below：

C#:

var originString = “123456&1482812036067&313644f42ecd4758b5e23b80e86efdc4&0af61531c6c04ac4ac910 d0cd59e6238”;

var md5 = MD5.Create();

var bs = md5.ComputeHash(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&0af61531c6c04ac4ac910 d0cd59e6238’;

$sign = strtoupper(md5($originString));

Get the signature strin 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=8516A3B52F9C8897F52239B19CD8A49

Use this string for signature verifying.

API List

Get current exchange rate

Description：

Get the current exchange rate of AUD to CNY, which is provided by WeChat, refreshes in a day. This exchange rate is only for reference.

API address

https://www.omipay.com.au/omipay/api/v2/GetExchangeRate

Parameters (except the sign verifying parameters, all the APIs are as the same.)

Field	Type	Example	Description
currency	String	AUD	The currency code which follows theISO-4217 standard.
base_currency	String	CNY
platform	String	WECHATPAY	Not mandatory, defaults WECHATPAY
language	String	EN	Not mandatory, defaults CHS

Success returns:

Field	Type	Example	Description
return_code	String	SUCCESS	When execute succeed, returns SUCCESS,it shows the result of API execution.
rate	Decimal	5.01540000	Current exchange rate

Fail returns:

Field	Type	Example	Description
return_code	String	FAIL	When execute failed,returns FAIL
error_code	String	SYSTEM_ERROR	Code of error
error_msg	String	System error	Description of error

Error code list

Error Code	Description
PARAMETER_INVALID	Invalid parameters, may caused by mandatory parameter missing, or parameter data type not correct.
SIGN_TIMEOUT	Time stamp is expired. The timestamp is less for more than 5 minutes to server time.
MERCHANTNO_INVALID	Merchant number is invalid. Please check the merchant number from merchant background system.
SIGN_ERROR	Signature check failed. Please check the signature string.
SYSTEM_ERROR	System unhandled error.

Request example:

https://www.omipay.com.au/omipay/api/v2/GetExchangeRate? m_number= 123456&timestamp= 1482812036067&nonce_str= 313644f42ecd4758b5e2 3b80e86efdc4&sign=8516A3B52F9C8897F52239B19CD8A499&currency=AUD&base_currency=CNY

Success returns example:

}

"return_code": "SUCCESS",

"rate": 5.01540000

}

Fail returns example:

}

"return_code": "FAIL",

"rate": "SIGN_TIMEOUT"

"error_msg": "Sign time out"

}

Make QRCode Order

Description：

QRCode order suits for the scene of non-WeChat client web based 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 to call the WeChat Payment function.

API address

https://www.omipay.com.au/omipay/api/v2/MakeQROrder

Parameters

Parameter	Type	Example	Description
order_name	String	Test_Order	The simple order information.
currency	String	AUD	Currency code of the order.
amount	int	100	Order 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.00
notify_url	String		Notification URL for transaction success. When this order is pay succeed, will send a notification to such URL. Refers to section 2.6.
out_order_no	String		Out order number. The notification data of transaction would include this field. So, it best be unique, in order to identify the order.
platform	String	ALIPAY	payment platform of this order.
language	String	EN	Not mandatory, defaults CHS.

Success returns:

Field	Type	Example	Description
return_code	String	SUCCESS	SUCCESS
order_no	String		Omipay order number, 32 characters length.
qrcode	String		String for QRCode.
pay_url	String		The 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:

Field	Type	Example	Description
return_code	String	FAIL	FAIL
error_code	String	SYSTEM_ERROR	Code of error
error_msg	String	Description of error	Description of error

Error Code list

Error Code	Description
PARAMETER_INVALID	Invalid parameters.
SIGN_TIMEOUT	Time stamp expires.
MERCHANTNO_INVALID	Merchant number is invalid.
SIGN_ERROR	Signature check failed.
SYSTEM_ERROR	System unhandled error.

Request example:

https://www.omipay.com.au/omipay/api/v2/MakeQROrder? m_number= 123456&timestamp= 1482812036067&nonce_str=313644f42ecd4758b5e2 3b80e86efdc4&sign=8516A3B52F9C8897F52239B19CD8A499&order_name= 测 试 商 品 &currency=AUD&amount=100&notify_url=http://your_site.com/receive_notify .html&out_order_no=SEORD000001

Addition comments:

The flow of QRCode payment:

1） Merchant create order in Web or PC Online-Store;

2） Call Omipay MakeQRCodeOrder API;

3） 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.

4） Customer scan this QRCode with WeChat/Alipay APP on mobile phone.

5） Customer finish the payment.

6） Omipay send transaction notification data to merchant.

Success returns example

}

"return_code": "SUCCESS",

"order_no": "bc112874260946a2af2b7107825e6ce2",

"qrcode" : "………………. ",

"pay_url" : "https://www.omipay.com.au/Omipay/pay/qrpay?paycode=xxxxxxxxx"

}

Fail returns example

}

"return_code": "FAIL",

"rate": "SIGN_TIMEOUT"

"error_msg": "Sign timeout"

}

Description of payment page:

1） 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.

2） For accessing the pay_url, the following parameters are required.

Field	Type	Example	Description
m_number	String
timestamp	String	1482812036067	Time stamp, refer to Timestamp in Parameter Rules
noncestring	String		Random string, refer to Nonce string in Parameter Rules
sign	String		Sign string
redirect_url	String		Browser will redirect to such url when payment done.

Make JSAPI Order

Description：

1)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.

2)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.

API address

https://www.omipay.com.au/omipay/api/v2/MakeJSAPIOrder

Parameters

Field	Type	Example	Description
order_name	String		The simple order information.
currency	String	AUD	Currency code of the order.
amount	int	100	Order 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.00
notify_url	String		Notification URL for transaction success. When this order is pay succeed, will send a notification to such URL. Refers to section 2.6.
redirect_url	String		Redirecting URL for transaction success. When this order is pay succeed, web browser will auto redirect to such URL.
out_order_no	String		Out order number. The notification data of transaction would include this field. So, it best be unique, in order to identify the order.
language	String	EN	Not mandatory, defaults CHS.

Success returns:

Field	Type	Example	Description
return_code	String	SUCCESS	SUCCESS
order_no	String		Omipay order number, 32 characters length.
pay_url	String		URL for payment. Merchant should lead user to access this URL.

Fail returns:

Field	Type	Example	Description
return_code	String	FAIL	FAIL
error_code	String	SYSTEM_ERROR	Code of error
error_msg	String	System error	Description of error

Error Code lis

Error Code	Description
PARAMETER_INVALID	Invalid parameters.
SIGN_TIMEOUT	Time stamp expires.
MERCHANTNO_INVALID	Merchant number is invalid.
SIGN_ERROR	Signature check failed.
SYSTEM_ERROR	System unhandled error.
WEBSTORE_NOT_EXISTS	This merchant don’t have the WESTORE type organization.

Request example:

https://www.omipay.com.au/omipay/api/v2/MakeJSAPIOrder? m_number=123456&timestamp=1482812036067&nonce_str=313644f42ecd4758b5e23 b80e86efdc4&sign=8516A3B52F9C8897F52239B19CD8A499&order_name= TEST_ORDER &currency=AUD&amount=100&redirect_url=http://your_site.com/redirect_to. html&amount=100&notify_url=http://your_site.com/receive_notify.html&out _order_no=SEORD000001

Success returns example:

}

"return_code": "SUCCESS",

"pay_url" : "………………. ",

}

Fail returns example:

}

"return_code": "FAIL",

"rate": "SIGN_TIMEOUT"

"error_msg": "Time stamp expires."

}

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

https://www.omipay.com.au/omipay/api/v2/MakeScanOrder

Parameters

Parameters	Type	Example	Description
order_name	String	TEST_ORDER	The simple order information.
currency	String	AUD	Currency code of the order.
amount	int	100	Order 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.00
notify_url	String		Notification URL for transaction success. When this order is pay succeed, will send a notification to such URL. Refers to section 2.6.
qrcode	String		Customer’s payment QRCode.
pos_no	String		POS Device number.
out_order_no	String		Out order number. The notification data of transaction would include this field. So, it best be unique, in order to identify the order.

Success returns

Field	Type	Example	Description
return_code	String	SUCCESS	SUCCESS
order_no	String		Omipay order number, 32 characters length.
out_order_no	String		Out order number.
order_time	String		Order pay time, in format of yyyyMMddHHmmss

Fail returns

Field	Type	Example	Description
return_code	String	FAIL	FAIL
error_code	String	SYSTEM_ERROR	Code of error
error_msg	String	Server error	Description of erro
order_no	String		If error_code = “USERPAYING”, then returns this field. Refers to Addition comments.

Error Code list

Error Code	Description
PARAMETER_INVALID	Invalid parameters.
SIGN_TIMEOUT	Time stamp expires.
MERCHANTNO_INVALID	Merchant number is invalid.
SIGN_ERROR	Signature check failed.
SYSTEM_ERROR	System unhandled error.
USERPAYING	This order is already paid.
ORDER_PAID	This order is already paid.
POS_NOT_REGISTERED	POS device is not registered.
NOT_ENOUGH	Not enough fee balance in user’s WeChat Wallet.
CARD_NOT_SUPPORT	User’s card type is not supported by WeChat Pay.
ORDER_CLOSED	Order is already closed.
QRCODE_EXPIRED	QRCode is expired.
QRCODE_ERROR	QRCode error.
AMOUNT_INVALID	Amount is invalid. When amount exceeds the up limit of payment platform, or exceeds the min amount of payment platform, this error occurs.

Request example:

https://www.omipay.com.au/omipay/api/v2/MakeScanOrder? m_number=123456&timestamp=1482812036067&nonce_str=313644f42ecd4758b5e23 b80e86efdc4&sign=8516A3B52F9C8897F52239B19CD8A499&order_name= Test_Orde &currency=AUD&amount=100&notify_url=http://your_site.com/receive_notify. html&qrcode=123abc123&pos_no=posno_123&out_order_no=SEORD000001

Addition comments:

The flow of Scan payment:

1） Merchant create the order in POS System, and show the amount of such order to customer;

2） Customer show the Payment QRCode of WeChat Wallet;

3） Merchant scan the QRCode with POS Device, and call MakeScanOrder API to create payment order;

4） Omipay server solves the request, meanwhile, merchant waits for the result of order;

5） 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);

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.

Query Order Status

Description：

Merchant could call this API to get the status of order.

API address:

https://www.omipay.com.au/omipay/api/v2/QueryOrder

Parameters

Parameter	Type	Example	Description
order_no	String		Omipay Order number
language	String	EN

Success returns:

Field	Type	Example	Description
return_code	String	SUCCESS	SUCCESS
result_code	String	PAID	order status
out_order_no	String		The out order no value which is sent by merchant when calls pay api.
currency	String	AUD	order currency code, which is defined in ISO 4217 standard. Currently, it always be AUD.
amount	int	100	amount in order currency type.(AUD)
order_time	String		Order create time, in format of yyyyMMddHHmmss
pay_time	String		Order pay time, in format of yyyyMMddHHmmss ; If order is not payed, the field value is empty string.
exchange_rate	int		Exchange rete of order currency type(AUD) to CNY; 10^8 times of real exchange rate value.
pay_currency	String	CNY	The currency no which customer actually pay.
cny_amount	int		amount in pay_currency .

Fail returns

Field	Type	Example	Description
return_code	String	FAIL	FAIL
error_code	String	SYSTEM_ERROR	Code of error
error_msg	String	Server error	Description of erro

Error code list:

Error Code	Description
PARAMETER_INVALID	Invalid parameters.
SIGN_TIMEOUT	Time stamp expires.
MERCHANTNO_INVALID	Merchant number is invalid.
SIGN_ERROR	Signature check failed.
SYSTEM_ERROR	System unhandled error.
PERMISSION_ERROR	Permission error, Occurs when the order number is not belongs to current merchant.

Request example

https://www.omipay.com.au/omipay/api/v2/QueryOrder? m_number= 123456&timestamp= 1482812036067&nonce_str= 313644f42ecd4758b5e2 3b80e86efdc4&sign=8516A3B52F9C8897F52239B19CD8A499&order_no=bc112874260 946a2af2b7107825e6ce2

Success returns example

}

"return_code": "SUCCESS",

"result_code": "PAID",

"currency" : "AUD",

"amount" : 100

"pay_currency": "CNY",

"pay_amount": 561,

"order_time" : "20161227105530",

"pay_time" : "20161227105602"

"exchange_rate" : "650000000"

}

Fail returns example

}

"return_code": "FAIL",

"rate": "SIGN_TIMEOUT"

"error_msg": "Time stamp expires"

}

Order status list:

Status	Description
READY	Order is created, but not payed.
PAYING	Customer is now paying.
PAID	Customer is already payed.
CLOSED	Order is closed. (Settled by Omipay)
CANCELLED	Order is cancelled.
FAILED	Customer 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.

Text Encoding	UTF8
Http Header	Content-Type=application/json
Data Sending Format	Data is transferred in request body, in JSON format.
Returns Data Type	application/json

Parameters:

Parameter	Type	Example	Description
nonce_str	String		Random nonce string.
timestamp	Long		Time stamp
sign	String		Signature string
order_no	String		Omipay order no.
out_order_no	String		Out order no.
currency	String	AUD	order currency code, which is defined in ISO 4217 standard. Currently, it always be AUD.
amount	int	100	amount in order currency type.(AUD)
pay_currency	String	CNY	The currency no which customer actually pay.
pay_amount	int	561	amount in pay_currency .
order_time	String		Order create time, in format of yyyyMMddHHmmss
pay_time	String		Order pay time, in format of yyyyMMddHHmmss ; If order is not payed, the field value is empty string.
exchange_rate	int		Exchange rete of order currency type(AUD) to CNY; 10^8 times of real exchange rate value.

Notice：Merchant has to verify the sign information when receives the notification to prevent of the third-party attack.

Merchant returns:

Field	Type	Example	Description
return_code	String	SUCCESS	Must be SUCCESS

Refund

Description：

Merchant could call this method to refund.

API address:

https://www.omipay.com.au/omipay/api/v2/Refund

Parameters

Parameters	Type	Example	Description
order_no	String		Omipay Order number which is going to be refunded.
out_refund_no	String		Out refund no.
amount	int	100	Refund amount in order currency.
language	String	EN

Success returns

Field	Type	Example	Description
return_code	String	SUCCESS	SUCCESS
refund_no	String		Omipay refund bill No.
currency	String	AUD	Currency No of refund.
amount	int	100	Refund amount
refund_time	String		Refund time ， in format of yyyyMMddHHmmss

Fail returns

Field	Type	Example	Description
return_code	String	FAIL	FAIL
error_code	String	SYSTEM_ERROR	Code of error
error_msg	String	Server error	Description of error

Error code list

Error Code	Description
PARAMETER_INVALID	Invalid parameters.
SIGN_TIMEOUT	Time stamp expires.
MERCHANTNO_INVALID	Merchant number is invalid.
SIGN_ERROR	Signature check failed.
SYSTEM_ERROR	System unhandled error.
PERMISSION_ERROR	Permission error, Occurs when the order number is not belongs to current merchant.
ORDER_NO_ERROR	Order No error, Occurs when the order No is wrong.
ORDER_NOT_PAID	Order is not paid.
AMOUNT_OVER_LIMIT	Refund amount is exceeds the limit.

Request example:

https://www.omipay.com.au/omipay/api/v2/Refund? m_number= 123456&timestamp= 1482812036067&nonce_str= 313644f42ecd4758b5e2 3b80e86efdc4&sign=8516A3B52F9C8897F52239B19CD8A499&order_no=bc112874260 946a2af2b7107825e6ce2&out_refund_no=xxxxxxx&amount=100

Success returns:

}

"return_code": "SUCCESS",

"refund_no": "ADDFGHJKL",

"currency" : "AUD",

"amount" : 100,

"refund_time" : "20161227105530"

}

Fail returns:

}

"return_code": "FAIL",

"rate": "SIGN_TIMEOUT"

"error_msg": "Time stamp expires."

}

Additional comments：

1） Refund is based on transaction, each refund bill has hooked with a specific transaction.

2） An order could be refunded multiple times. The total amount of such refunds shouldn’t be more than order amount.

3） 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 Refund

Description：

Merchant should call this api to get the status of specific refund.

API address：

https://www.omipay.com.au/omipay/api/v2/QueryRefund

Parameters:

Parameter	Type	Example	Description
refund_no	String		Refund no of Omipay.
language	String	EN

Success returns:

Field	Type	Example	Description
return_code	String	SUCCESS	SUCCESS
result_code	String	CLOSED	status of refund.
out_refund_no	String		Out order No.
currency	String	AUD	Currency No of refund
amount	int	100	amount in order currency type.
refund_time	String		Refund create date. In formats of yyyyMMddHHmmss
success_time	String		Actually refund time. In formats of yyyyMMddHHmmss; If refund status is not CLOSED, then returns empty string.

Fail returns:

Field	Type	Example	Description
return_code	String	FAIL	FAIL
error_code	String	SYSTEM_ERROR	Code of error
error_msg	String	Server error	Description of error

Error code list

Error code	Description
PARAMETER_INVALID	Invalid parameters.
SIGN_TIMEOUT	Time stamp expires.
MERCHANTNO_INVALID	Merchant number is invalid.
SIGN_ERROR	Signature check failed.
SYSTEM_ERROR	System unhandled error.
PERMISSION_ERROR	Permission error, Occurs when the order number is not belongs to current merchant.
REFUND_NO_ERROR	Refund No is not correct.

Request example

https://www.omipay.com.au/omipay/api/v2/QueryRefund? m_number= 123456&timestamp= 1482812036067&nonce_str= 313644f42ecd4758b5e2 3b80e86efdc4&sign=8516A3B52F9C8897F52239B19CD8A499&refund_no=bc11287426 0946a2af2b7107825e6ce2

Success returns:

}

"return_code": "SUCCESS",

"result_code": "CLOSED",

"currency" : "AUD",

"amount" : 100,

"refund_time" : "20161227105530",

"success_time" : "20161227105602",

}

Fail returns:

}

"return_code": "FAIL",

"rate": "SIGN_TIMEOUT"

"error_msg": "Time stamp expires"

}

Refund status list:

Status	Description
Applied	Customer is applied the refund request.
MerchantConfirmed	Merchant accepted the refund request, and submitted to payment platform.
OrganizationConfirmed	Payment platform is confirmed refund.
OrganizationPayback	Payment platform is already refunded.
Closed	Refund flow is finished, flow closed.
MerchantRejected	Merchant rejected the refund request.
TimeoutClosed	The refund request is over the time limit for refunding of this order.
OrganizationFailed	Payment platform operation failed.
CustomerCancelled	Customer cancelled refund request.