List of the authorized request parameters
URL of the authorization request is https://<SERVER-NAME>/pay/order.cfm
The full list of the authorized request parameters is given in table below:
Parameter | Mandatory field | Adopted values | Default value | Description |
Merchant_ID | Yes | Number | The enterprise identifier in IPS Assist | |
OrderNumber | Yes | 128 characters | Order number in the enterprise payments system | |
Delay | No | 0 – one-stage operation | 0 | Attribute of a bankcard authorization for the double-stage operation |
Language | No | RU – Russian, | Language of legal entity/enterprise | Language of authorization pages |
OrderComment | No | 4000 characters | Comment | |
OrderAmount | Yes | Number, 15 digits, two digits after the delimiter (delimiter '.') | Payment amount, in original currency (e.g., 10.34) | |
OrderCurrency | No | 3 characters | Currency of legal entity/enterprise | Code of currency of the OrderAmount. |
Lastname | No | 70 characters | Customer's last name | |
Firstname | No | 70 characters | Customer's first name | |
Middlename | No | 70 characters | Customer's middle name | |
No | 128 characters | Customer's e-mail | ||
Address | No | 256 characters | Customer's address | |
HomePhone | No | 64 characters | Customer's home phone number | |
WorkPhone | No | 20 characters | Customer's work phone number | |
MobilePhone | No | 20 characters | Customer's mobile phone number | |
Country | No | 3 characters | Customer's country | |
State | No | 3 characters | Customer's region | |
City | No | 70 characters | Customer's city | |
Zip | No | 25 characters | Customer's post zip code | |
URL_RETURN | No | 256 characters | Page URL, to where a customer should return after performing his/her payment in the system (option "Go to the shop page" should be enabled in merchant's settings in Personal account). It is recommended to use HTTPS protocol for secure communication. | |
URL_RETURN_OK | No | 256 characters | URL_RETURN parameter value, or, if none, return URL parameter after successful authorization, specified in Personal account | Page URL, to where a customer should return after successful performing his/her payment in IPS Assist (option "Go to the shop page" should be enabled in merchant's settings in Personal account). It is recommended to use HTTPS protocol for secure communication. |
URL_RETURN_NO | No | 256 characters | URL_RETURN parameter value, or, if none, return URL specified in Personal account | Page URL, to where a customer should return if the payment is not performed in IPS Assist or payment is still in progress (current payment status "In Progress"), see details. The option "Go to the shop using return URL" should be enabled in merchant's settings in Personal account. It is recommended to use HTTPS protocol for secure communication. |
CardPayment | No | 1 – payment with using bankcard; | 1 | A customer can perform his/her payment using bankcard, if parameter value 1 has been sent, or the parameter is missing (and bankcard payments are enable for the enterprise). |
ERIPPayment | No | 1 – payment with using ERIP; | 1 | A customer can perform his/her payment using ERIP, if parameter value 1 has been sent, or the parameter is missing (and ERIP payments are enable for the enterprise). |
MobiconPayment | No | 1 – use Mobicon payment system, | 1 | A customer can perform his/her payment using Mobicon payment system, if parameter value 1 has been sent, or the parameter is missing (and Mobicon payments are enable for the enterprise) |
GooglePayPayment | No | 1; 0 | 0 | Payment via Google Pay attribute (=1) |
ApplePayPayment | No | 1; 0 | 0 | Payment via ApplePay attribute (=1) |
SamsungPayPayment | No | 1; 0 | 0 | Payment via SamsungPay attribute (=1) |
Signature | No* | String | The string is joined according the determined rules. Then the MD5 hash is prepared from this string. Hash is signed by private RSA key of the merchant. Key length is 1024. Received bit sequence is a signature. Signature is transferred as BASE64 coded string. Attention! The parameter is necessary in order to protect the transmitted data from the possibility of their substitution by intruders. You should also enable the setting for check value or signature in the Personal account. | |
Checkvalue | No* | String | Request validation code. The string has to be generated as follows: uppercase(md5(uppercase(md5(SALT) + md5(Х)))), where SALT – secret word; Х – the string joined according the determined rules. Note. If the merchant uses request validation code without delimiters, please, contact the support team support@belassist.by. Attention! The parameter is necessary in order to protect the transmitted data from the possibility of their substitution by intruders. You should also enable the setting for check value or signature in the Personal account. | |
RecurringIndicator | No | 1 – recurrent payment 0 – nonrecurrent payment | 0 | Recurring payment indicator. |
RecurringMinAmount | No/Yes | Number, 15 digits, two digits after the delimiter (delimiter '.') | Min amount of recurrent payments. Mandatory if RecurringIndicator = 1 | |
RecurringMaxAmount | No/Yes | Number, 15 digits, two digits after the delimiter (delimiter '.') | Max Amount of recurrent payments. Mandatory if RecurringIndicator = 1 | |
RecurringPeriod | No/Yes | Number, 3 digits | Frequency of recurrent payments in days. Mandatory if RecurringIndicator = 1 | |
RecurringMaxDate | No/Yes | Date as string in DD.MM.YYYY format | The end date of recurrent payments. Mandatory if RecurringIndicator = 1 |
* In order to protect the transmitted data from the possibility of their substitution by intruders, one of the parameters (Signature or Checkvalue) must be passed, and the setting for the check value (or signature) in the Personal account must also be enabled.
All request parameters are automatically validated. The validation rules are given in the table "The validation rules for input parameters".
If more than one parameter specifying the type of payment means (CardPayment, WMPayment etc.) has value 1, a customer can choose a method of payment on the payments page of IPS Assist. If these parameters are not sent, a user can also select a method of payment on IPS Assist payment page from all those available for this enterprise. If all these parameters have the value 0, then it results to error.
An example of a button with all necessary parameters:
<FORM ACTION="https://<SERVER-NAME>/pay/order.cfm" METHOD="POST"> <INPUT TYPE="HIDDEN" NAME="Merchant_ID" VALUE="Your Merchant_ID"> <INPUT TYPE="HIDDEN" NAME="OrderNumber" VALUE="A20042011_28"> <INPUT TYPE="HIDDEN" NAME="OrderAmount" VALUE="237.40"> <INPUT TYPE="HIDDEN" NAME="OrderCurrency" VALUE="USD"> <INPUT TYPE="HIDDEN" NAME="Delay" VALUE="0"> <INPUT TYPE="HIDDEN" NAME="Language" VALUE="RU"> <INPUT TYPE="HIDDEN" NAME="Email" VALUE="test@test.by"> <INPUT TYPE="HIDDEN" NAME="OrderComment" VALUE="Order payment 28-A"> <INPUT TYPE="HIDDEN" NAME="URL_RETURN_OK" VALUE="http://www.URL.by/yes"> <INPUT TYPE="HIDDEN" NAME="URL_RETURN_NO" VALUE="http://www.URL.by/no"> <INPUT TYPE="HIDDEN" NAME="CardPayment" VALUE="1"> <INPUT TYPE="HIDDEN" NAME="WMPayment" VALUE="0"> <INPUT TYPE="HIDDEN" NAME="YMPayment" VALUE="0"> <INPUT TYPE="SUBMIT" NAME="Submit" VALUE="Buy"> </FORM>
After pressing this button, a customer is redirected to the authorized pages of IPS Assist, where he/she can enter the other personal data and perform payments using his/her bankcard. The information, such as a customer's first name, second name and e-mail are mandatory (the parameters Firstname, Lastname, Email) and should be either send in the authorized request, or entered on the payment page.
Please, note that the original amount and the currency code send by the enterprise in the payment parameters, when redirecting a customer to the authorization pages of IPS Assist, can differ from the authorization amount and currency. The authorization amount and currency are the amount and currency, which were sent to Processing Center for the bankcard authorization (the amount is normally in Belarussian Rubles). For example, if the payment original amount is 100 USD, then the authorization amount made, for example with rate 1 USD=1,9608 BYN, equals to 196,08 BYN.
After successful payment, the order in IPS Assist adopts the status Approved; all possible order statuses see "OrderState field values".
Customer's return to Internet shop page after purchase
After performing payment in IPS Assist a customer can see the page with the information of the payment results (for example, "Completed"), as well as the payment, customer and enterprise data.
You can also set up a customer's automatic redirecting to the enterprise web site after performing the payment in IPS Assist. For this, after the authorization select the action "Go to the shop's page" in Personal account in the section "Merchants settings", tab "Payments settings". If the authorization is successful, a customer is redirected to the address that you specified in the parameter URL_RETURN_OK. In the other cases a customer is redirected to the address specified in the parameter URL_RETURN or URL_RETURN_NO. However, during the authorization by bankcard this address is supplemented with the parameters Billnumber (complete unique order number in IPS Assist) and OrderNumber (order number in the enterprise payments system) corresponding to the given payment, in the following format:
http://URL return/?billnumber=complete_unique_order_number&ordernumber=order_number
If the parameters URL_RETURN_OK and URL_RETURN_NO are not sent in the authorization request, then URL_RETURN parameter value is used for a customer's automatic redirection. If this parameter is also not sent, then the return URL_RETURN_OK and URL specified in "Merchants settings" section in Personal account are used.
When customer returns to the merchant site the value of the order number is always transmitted as URL-encoded string: all non alpha-numeric characters (except '-' and '_'.) are replaced by the percent sign '%' followed by two digits hex code; spaces are replaced by '+' sign. This is important when the order number contains characters of non latin alphabet or some special symbols.
When using the option of a customer's return to the shop, it is recommended to sent an additional request about the authorization result to IPS Assist server after receiving data about the paid order at URL_RETURN_OK (see details) in order to make sure the order payments have been performed. It is recommended as well to send an additional request about the authorization result to IPS Assist server after receiving data about the paid order at URL_RETURN and URL_RETURN_NO, because a customer is redirected to these addresses with different payment state, including the state "In process".
