Authentication

HTTP Actions

APIs that adhere to the REST architectural constraints are called RESTful APIs, or simply REST APIs. The iMerchant HTTP-based REST APIs are defined with the following aspects:

Standard HTTP methods
For example: GET and POST

This table describes the supported HTTP methods.

Digital Signature

In order to ensure the authenticity and integrity of a message, software or digital document, digital signature is required. It’s the equivalent of a handwritten signature or stamped seal, but it offers far more inherent security.

Digital signatures work through public key cryptography’s two mutually authenticating cryptographic keys. The individual who creates the digital signature uses a private key to encrypt signature-related data, while the only way to decrypt that data is with the signer’s public key (TechTarget).

Signature string

Whether it’s a request or a response, or it’s using GET or POST, the signature query string is assembled into a string as follows:

1. Except for the sign field, all parameters are sorted by ASCII code from smallest to largest using QueryString format (i.e. key1=value1&key2=value2…).The null value is not passed and does not participate in the signature group string
2. All parameters refer to all non-null parameters that actually appear in the communication process. Even if the fields are not defined in the api, they still need to participate in the signature query string. If the field test is not in the api, and test has a value when the merchant requests it or iMerchant responds, this field must also participate in the signature query string
3. In the query string, the field name and the field value are the original values, and the URL will not be encoded
4. The response or notification messages returned by iMerchant may have additional parameters due to the upgrade. Please allow this when validating the response signature

for example:

there are the below specific field as below when call an api:.

bid, amount, currency, attach

The actual value when call the api in each field：

bid=py_live_0I9fPdXQWhzZPurCVe8y2AHx，amount=100，currency=HKD，attach=123

The correct query string is：

amount=100&attach=123&bid=py_live_0I9fPdXQWhzZPurCVe8y2AHx&currency=HKD

Algorithm

We support MD5 signature only at the current stage

MD5 is a digest generation algorithm that performs MD5 operations by adding the content of the merchant's communication key after the original signature string, and the digest string formed is the result of the signature. To facilitate comparison, the signature result is uniformly converted to uppercase characters.

An MD5 signature, also called an MD5 path or hash. A MD5 hash is typically expressed as a 32-digit hexadecimal number (this is an example of MD5 hash : 703862f5d0ee949ef9fc97c4be2dc6f5). This hash represents a signature (or footprint) of the data (data being usually a file or a text).

MD5 signature calculation formula:

sign=MD5(query string&key=merchant key) toUpperCase

• For example – signature string:

amount=100&bid=py_live_0I9fPdXQWhzZPurCVe8y2AHx&currency=HKD

• Merchant key:

8db4a013a8b515349c307f1e448ce836

• Signature Result:

sign=md5(amount=100&bid=py_live_0I9fPdXQWhzZPurCVe8y2AHx&currency=HKD&key=8db4a013a8b515349c307f1e448ce836)= CAE4482E653ECB490145409E1DA20CCE

API Endpoints

• BID

BID is the account number generated by iMerchant for the merchant. It is a string of 32 bits long to uniquely identify the merchant generated by the system. It comes after the URL as a parameter url?bid=xxxxxx to visit the payment page.

For example:

https://gw.iMerchan .com/gateway/pay?bid=py_live_0I9fPdXQWhzZPurCVe8y2AHx

• notify_url

This parameter is configured by the merchant and cannot be notified if it is not configured.

Once the payment succeeded, iMerchant server will return a notice to the merchant server. The HTTP method is by GET. The form is:

Url?transaction_id=38412017311169761509679088&amount=9000&end_time=1505888072&currency=USD&sign=99FAA2D3E52374B5287074B6F916D8E4

Transaction_id: A 26 digital string transaction ID which can be used as an order query and order refund identification. 
Amount: Payment amount. The unit is cents. 
End_time: Time of the payment made. Timestamp is in seconds.
Currency: Monetary unit of payment

• return_url

This parameter is configured by the merchant, and if it is not configured, it will default to iMerchant’s default results page.

Once the payment succeeded, the iMerchant server will call this URL with by GET with paramaters. The form is:

Url?transaction_id=38412017311169761509679088&amount=9000&end_time=1505888072&currency=USD

Transaction_id: A payment stream ID. It is a 12 character string consisting of numbers, lowercase letters, and uppercase letters which can be used as an order query, and order refund identification
Amount: Payment amount. The unit is cents. 
End_time: Time of the payment made. Timestamp is in seconds.
Currency: Monetary unit of payment