General provisions
“The “Settlement” system is an automated information system of a single settlement and information space (SSIS) created by the National Bank of the Republic of Belarus in order to simplify the organization of accepting payments from individuals and legal entities.
Payment through SSIS allows you to pay for a purchase from your card account using Internet banking, ATMs and information kiosks of many banks in the Republic of Belarus. You can pay in cash through SSIS at bank cash desks or through cash-in devices.
This document is intended for merchants wishing to accept payments for goods/services on their websites using SSIS. Organization of payment using SSIS is carried out through IPS Assist.
Using SSIS, you can make on-demand payments or advance payments.
Payments on demand
On-demand payments are made by the customer at a time when buying a product/service.
Payment against an invoice issued using a web service
The web service for creating a bill accepts bill parameters (HTTP POST/SOAP formats) and returns (if the bill is created successfully) the payment token/ID corresponding to this bill. IPS Assist sends a notification via E-mail to the customer's address specified in the parameters with the order number (payment token/ID) for payment in the SSIS system.
Subj | The bill has been invoiced for payment |
Text | Hello, Test Testov , We inform you that bill # 15912778124 on amount of 88.80 BYN You can pay it till 11.09.2020 16:36:55 (GMT +03:00). To pay the bill, use the “Settlement” system (SSIS). To quickly search, use the SSIS service code (481287) Order number in the SSIS system: 15912778124 Please address internet-shop #1 at shop 1@ testpost . by in case of any questions concerning about this bill. _____________ With best regards, ASSIST Customer Service Team |
The notification template must be discussed with support service ( support@belassist.by ).
The customer can pay the bill in the SSIS system at any time within the specified period. To set up a due date for paying bills, the merchant should contact the technical support service (support@belassist.by).
Request URL to create a bill:
https://<SERVER-NAME>/bill/createbill.cfm
List of request parameters:
Parameter | Mandatory field | Adopted values | Default value | Description |
Merchant_ID | Yes | Number | The merchant identifier in IPS Assist | |
Login | Yes | 8 - 20 characters | Login (Latin letters, digits and symbol _) | |
Password | Yes | 8 - 20 characters | Password (Latin letters and digits) | |
Bill | Yes/No* | 30 characters (digits and latin letters) | Unique bill number (in creating order will be used as OrderNumber, and also as a number for payment in SSIS) | |
Bill _ amount | Yes | Number | Bill amount (OrderAmount in order ) | |
Bill _ currency | Yes | String | Bill currency (OrderCurrency BYN only) | |
Bill _ comment | No | String | Comment (OrderComment in order ) | |
Customer_Name | No | String | Customer's name (FirstName in order ) | |
Customer _ Lastname | No | String | Customer's last name (LastName in order ) | |
Customer_Middlename | No | String | Customer's middle name (MiddleName in order ) | |
Customer _ Email | Yes/No** | String | Customer's e-mail (Email in order) | |
Customer _ Phone | No | String | Customer's phone number (HomePhone in order ) | |
Customer _ Mobile | No | String | Customer's mobile phone number (MobilePhone in order ) | |
Language | No | RU EN | Setting of basic merchant account language | Language of authorized pages |
Pay _ until | No | Date/time | 1 day | Expire date of bill payment (date and time in GMT): YYYYMMDDThhmm, when parameter is not passed then its value is calculated based on merchant settings |
SendNotification | No | Number | Depending on merchant settings | Bill sending by E-mail: 0 – not send, 1 – send by E-mail |
Checkvalue | Yes | String | Request validation code*** |
*parameter Bill is not mandatory in case when automatic bill numbering is switched on.
**If the value of the E-mail address is not sent, sending the bill by E-mail is not possible and the SendNotification value is ignored.
***Check value is calculated by following formula:
uppercase(md5(uppercase(md5(SALT) + md5(Х)))) , where SALT – secret word; Х – result of string concatenation (with semicolon (;) as delimiter) of the request parameters in order as they located in table from top to bottom excluding DelayPayment, SendNotification, Checkvalue and CustomerNumber , '+' – string concatenation.
When bill with the same number is already exist then new bill is not created and an error is returned: " Bill with the specified number already exists ".
If request doesn't contain mandatory parameters or wrong data format provided the new bill is not created and an error is returned (similar to the error of order creation with not enough or wrong parameters).
When unique payment token/ID cannot be created the new bill is not created and an error is returned: " Unique payment token/ID cannot be created ".
Example of bill creation request (HTTP POST):
<FORM ACTION="https://<SERVER-NAME>/bill/createbill.cfm" method="POST"> <INPUT TYPE="hidden" NAME="Merchant_ID" VALUE="Your Merchant_ID"> <INPUT TYPE="hidden" NAME="Login" VALUE="Your login"> <INPUT TYPE="hidden" NAME="Password" VALUE="Your password"> <INPUT TYPE="hidden" NAME="Bill" VALUE="Bill number"> <INPUT TYPE="hidden" NAME="Bill_amount" VALUE="Bill amount"> <INPUT TYPE="hidden" NAME="Bill_currency" VALUE="Bill currency"> <INPUT TYPE="hidden" NAME="Bill_comment" VALUE="Bill comment"> <INPUT TYPE="hidden" NAME="Customer_Name" VALUE="Customer name"> <INPUT TYPE="hidden" NAME="Customer_Lastname" VALUE="Customer lastname"> <INPUT TYPE="hidden" NAME="Customer_Middlename" VALUE="Customer middlename"> <INPUT TYPE="hidden" NAME="Customer_Email" VALUE="Customer Email"> <INPUT TYPE="hidden" NAME="Customer_Phone" VALUE="Customer phone"> <INPUT TYPE="hidden" NAME="Customer_Mobile" VALUE="Customer mobile phone"> <INPUT TYPE="hidden" NAME="Language" VALUE="Language of authorized pages"> <INPUT TYPE="hidden" NAME="Pay_until" VALUE="Expire date of bill payment"> <INPUT TYPE="hidden" NAME="SendNotification" VALUE="Bill sending flag"> <INPUT TYPE="hidden" NAME="Checkvalue" VALUE="Request validation code"> <INPUT TYPE="Submit"></FORM>
List of response parameters:
Parameter | Value |
Hash | Payment token/bill ID |
Example of return parameter in CSV format:
Hash: xKPWpz4ZzDe5A9anPhnN
In XML format:
<?xml version='1.0' encoding='utf-8' standalone='yes'?> <result firstcode="0" secondcode="0" count="1"> <return> <Hash>akPWp08t84MTQ9anTy30</Hash> </return> </result>
SOAP web-service description:
https://<SERVER_NAME>/bill/createbill.wsdl
Example of bill creation request:
<Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <Header/> <Body> <CreateBill> <Bill> <merchant_id>423422</merchant_id> <login>login</login> <password>password</password> <bill>123456</bill> <bill_amount>100.00</bill_amount> <bill_currency>BYN</bill_currency> <bill_comment></bill_comment> <customer_name>Test</customer_name> <customer_lastname>Testov</customer_lastname> <customer_middlename>Testovich</customer_middlename> <customer_email>test@testpost.by</customer_email> <customer_phone></customer_phone> <language>RU</language> <pay_until>20150611T1212</pay_until> <sendnotification>0</sendnotification> <checkvalue> AA3BC3F48B7FE23988044B53AA98F169</checkvalue> </Bill> </CreateBill> </Body> </Envelope>
Example of request result:
<soapenv:Envelope SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <SOAP-ENV:Body SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"> <ASS-NS:BillResponse xmlns:ASS-NS="http://www.paysecure.ru/ws/"> <return xsi:type="si:SOAPStruct" xmlns:si="http://www.paysecure.ru/type/"> <Hash xsi:type="xsd:string">6CPV7F4a0aWQg9XsXhrS</Hash> </return> </ASS-NS:BillResponse> </SOAP-ENV:Body>
Payment according to a bill issued from the Personal Account of IPS Assist
The Bills section is designed to obtain information about invoiced and paid bills; the section also allows you to create new bills, cancel invoiced bills, send issued bills by email to customers, pay invoiced bills and receive other necessary information about the bills and bill payments.
Separate button " Create new bill " allows the operator to create new bill directly from your personal account. Clicking this button opens a window for bill creation. Required parameters are marked with asterisks.
Bill creation window
List of the parameters for creating a new bill
Name | Description |
Common info | |
Merchant | Select from the drop down list available merchants for the current user. |
Bill # | The bill number that is defined by the enterprise. When bill auto-numbering is switched on IPS Assist side then this field can be empty. |
Bill amount | Bill amount |
Currency | Bill currency (select from the drop down list of currency codes). |
Comment | Bill comment |
Language | Customer language, which is used for E-mail messages and payment page (language of the merchant by default). |
Pay_until | Expire date of bill payment (date and time in GMT), by default 1 day. |
DelayPayment* | Check box. Attribute of a credit card authorization for the double-stage operation mode: 0- one-stage operation, 1 - double-stage operation. |
Customer info | |
Customer Number | Merchant's internal customer identification |
Last name* | Customer's last name |
First name* | Customer's name |
Middle Name | Customer's middle name |
Phone | Customer's phone number |
Mobile phone | Customer's mobile phone number |
Customer's E-mail address | |
Send bill* | Drop-down list: Don't send, Send via E-mail, Send via Email and SMS. |
*The parameter value can be set by default. In this case, the bill creation window will be opened with the already filled default values. During creating a bill, the values of these parameters can be changed by user. Please, contact support team (support@belassist.by ) to set the default parameters.
All changes are applied after pressing ' Save ' button.
If you select the 'View bill' option in the bill's context menu then the window 'Bill details' appears with selected bill. If you select the 'Edit bill' option in the bill's context menu you can also edit the bill parameters. Work in this window is carried out in the same way as in the Create new bill window.
Bill details window
Attention! If a template for notifying the customer about invoicing the bill for payment in the SSIS system is configured for the merchant (see example), then the customer will be able to pay the bill within the specified period using SSIS. If the merchant uses a standard notification template, the customer will receive a link to pay the bill using not only SSIS, but also other payment means. At the same time, no more than 48 hours are given for payment using SSIS. The operator transmitting the bill link to the customer in any way will lead to the same result.
On-demand payments from the Personal Account of IPS Assist
On-demand payments via payment pages
In order for the IPS Assist server to accept a payment authorization request, the merchant must send the following parameters:
- Merchant_ID – the merchant identifier in IPS Assist;
- OrderNumber – order number in the merchant's payment system corresponding to this payment;
- OrderAmount – purchase amount.
This is a minimum set of payment parameters that is transmitted from the merchant when the customer is redirected to the IPS Assist server, after which the customer enters personal data (full name, address, Email, telephone, etc.) and information about the payment means on the IPS Assist authorization pages.
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=" B20042011_27"> <INPUT TYPE="HIDDEN" NAME="OrderAmount" VALUE="205.50"> <INPUT TYPE="HIDDEN" NAME="OrderComment" VALUE="Example of an order payment"> <INPUT TYPE="SUBMIT" NAME="Submit" VALUE="Buy"> </FORM>
A customer, however, often enters his/her personal information (name, address, e-mail etc.) on the enterprise pages during registration. The merchant can send this information along with the payment parameters. In this case a customer enters on IPS Assist pages only the payment means data.
Example of a button with the payment parameters and the customer's personal data:
<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="A03032011_26"> <INPUT TYPE="HIDDEN" NAME="OrderAmount" VALUE="66.66"> <INPUT TYPE="HIDDEN" NAME="OrderCurrency" VALUE="BYN"> <INPUT TYPE="HIDDEN" NAME="FirstName" VALUE="Test"> <INPUT TYPE="HIDDEN" NAME="LastName" VALUE="Testov"> <INPUT TYPE="HIDDEN" NAME="Email" VALUE="test@assist.ru"> <INPUT TYPE="HIDDEN" NAME="OrderComment" VALUE="Example of an order payment"> <INPUT TYPE="SUBMIT" NAME="Submit" VALUE="Pay"> </FORM>
URL of the authorization request is:
https://<SERVER-NAME>/pay/order.cfm
The full list of the authorization request parameters is given in table below:
Parameter | Mandatory field | Adopted values | Default value | Description | |
Merchant_ID | Yes | Number | The merchant identifier in IPS Assist | ||
OrderNumber | Yes | 128 characters | Order number in the merchant payments system | ||
Delay | No | 0 – one-stage operation 1 – double-stage operation | 0 | Attribute of a bankcard authorization for the double-stage operation mode. | |
Language | No | RU – Russian, EN – English | Language of legal entity/enterprise | Language of authorized 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. | ||
Fax | No | 20 characters | Customer's fax 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 – pay 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 – use SSIS payment system, | 1 | A customer can perform his/her payment using SSIS payment system, if parameter value 1 has been sent, or the parameter is missing (and SSIS payments are enable for the merchant) | |
MobiconPayment | No | 1 – use MobiconPayment payment system, | 1 | A customer can perform his/her payment using MobiconPayment payment system, if parameter value 1 has been sent, or the parameter is missing (and MobiconPayment payments are enable for the merchant) | |
GooglePayPayment | No | 1; 0 | 0 | Payment via Google Pay attribute (=1) | |
ApplePayPayment | No | 1; 0 | 0 | Payment via Apple Pay attribute (=1) | |
SamsungPayPayment | No | 1; 0 | 0 | Payment via Samsung Pay attribute (=1) | |
Signature | No* | String | The string is joined according the determined rules. Then the MD5 hash prepared from this string. Hash is signed by private RSA key of the merchant. Key length - 1024. Received bit sequence is a signature. Signature is transferred 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 | Recurring payment indicator | |
RecurringMinAmount | No/Yes | Number, 15 digits, two digits after the delimiter (delimiter '.') | Min amount of recurrent payments. | ||
RecurringMaxAmount | No/Yes | Number, 15 digits, two digits after the delimiter (delimiter '.') | Max Amount of recurrent payments. | ||
RecurringPeriod | No/Yes | Number, 3 digits | Frequency of recurrent payments in days. | ||
RecurringMaxDate | No/Yes | Date as string in DD.MM.YYYY format | The end date of recurrent payments. | ||
Disable3DS | No | 0 - perform 3D-Secure authorization according to the merchant settings; | 0 | Flag of disabling 3-D Secure. |
* 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.
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="Ваш 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="Оплата заказа 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="ERIPPayment"VALUE="1"> <INPUT TYPE="SUBMIT" NAME="Submit"VALUE="Купить"> </FORM>
After completing the request, a payment receipt is displayed on the payment page, which indicates the payment status as “In Process”. The customer is invited to use the SSIS “Settlement” system to complete the payment. At the same time, a letter with the SSIS order number and instructions for completing the payment is sent to the customer’s email address.
On-demand payments via web service
A special web service allows a merchant to generate an order in SSIS without going to the payment page.
To work in this mode, the makeorder web service is provided.
Request URL for creating an order in SSIS:
https://<SERVER-NAME>/pay/makeorder.cfm
List of request parameters for creating an order in SSIS:
Parameter | Mandatory field | Adopted values | Default value | Description |
Merchant_ID | Yes | Number | The merchant identifier in IPS Assist | |
OrderNumber | Yes/No | 30 characters | Order number in the merchant payments system | |
OrderAmount | Yes | Number, 15 digits, two digits after the delimiter (delimiter '.') | Payment amount, in original currency (e.g., 10.34). | |
OrderCurrency | Yes | 3 characters | Currency of legal entity/merchant | Code of currency of the OrderAmount . |
OrderComment | No | 256 characters | Comment | |
Language | No | RU – Russian | Language of legal entity/merchant | Language of authorized pages |
Lastname | Yes | 30 characters |
| Customer's last name. |
Firstname | Yes | 30 characters |
| Customer's first name. |
Middlename | No | 30 characters |
| Customer's middle name. |
Yes | 128 characters |
| Customer's e-mail. | |
Address | No | 90 characters |
| Customer's address in the format: st. <30 characters>, h. <10 characters>, bldg. <10 characters>, apt. <10 characters> |
City | No | 30 characters |
| Customer's city. |
Signature | No * | String |
| The string is joined according the determined rules. Then the MD5 hash prepared from this string. Hash is signed by private RSA key of the merchant. Key length - 1024. Received bit sequence is a signature. Signature is transferred 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. |
* Must be send if the merchant uses the parameter for common orders.
An example of HTTP POST request
<FORM ACTION="https://SERVER-NAME/pay/makeorder.cfm " method="POST"> <INPUT TYPE="hidden" NAME="Merchant_ID" VALUE="Your Merchant_ID"> <INPUT TYPE="hidden" NAME="OrderNumber" VALUE="011001-10"> <INPUT TYPE="hidden" NAME="OrderAmount" VALUE="22"> <INPUT TYPE="hidden" NAME="OrderCurrency" VALUE="BYN"> <INPUT TYPE="hidden" NAME="OrderComment" VALUE="Order payment 011001-10"> <INPUT TYPE="hidden" NAME="Language" VALUE="RU"> <INPUT TYPE="hidden" NAME="Lastname" VALUE="Customer's last name"> <INPUT TYPE="hidden" NAME="Firstname" VALUE="Customer's first name"> <INPUT TYPE="hidden" NAME="Middlename" VALUE="Customer's middle name"> <INPUT TYPE="hidden" NAME="Email" VALUE=" Customer's Email"> <INPUT TYPE="hidden" NAME="Address" VALUE="Customer's address"> <INPUT TYPE="hidden" NAME="Homephone" VALUE="Customer's phone number"> <INPUT TYPE="hidden" NAME="City" VALUE="Customer's city"> <INPUT TYPE="Submit"></FORM>
List of response parameters:
Название | Значение |
ordernumber | Order number in the merchant payments system |
expirationtime | Expire date of payment (date and time in GMT): DD.MM.YYYY HH:MM:SS |
orderstate | |
eripordernumber | Order number in the SSIS system (the customer must enter it to complete the payment) |
An example of a response in JSON format after a successful order creation:
{"ordernumber":"ABC123", "expirationtime":"04.08.2017 13:06:00", "orderstate": "In Process", "eripordernumber":"21923958"}
An example of a response in JSON format after unsuccessful order creation or problems with parameters:
{"errorCode":"51", "errorMessage":"Customer first name must be specified"}
Advance payments
An merchant can receive either advance payments or on-demand payments through SSIS, depending on the system settings.
Advance payments are made to the customer’s personal account in the merchant’s payments system. The merchant informs the customer via email or SMS message the personal account number that the customer uses when paying in SSIS. Next, upon request from SSIS, a corresponding order is created in IPS Assist.
After successful payment by the customer to the specified personal account in SSIS, the paid order will be displayed in the order monitoring of Personal account IPS Assist.
To use advance payments, the merchant needs to send to IPS Assist a register of current personal accounts and customer debts. The registry is transferred as a csv file containing the following parameters.
Parameter | Mandatory field | Adopted values | Description |
Merchant_ID | Yes | Number | The merchant identifier in IPS Assist |
PersonalAccount | Yes | 30 characters | Personal account number, customer ID, etc. in the merchant system (the use of special characters is not allowed). Note. All alphabetic characters contained in the personal account number are converted into capital letters when loaded into IPS Assist. Therefore, account numbers must be generated in such a way as to exclude the possibility of non-unique account numbers appearing (for example, sequences of characters in the account number - ABC, abc, Abc, etc. will be considered the same). |
Debt | No | Number | Debt amount (12.2 – two digits after the delimiter, delimiter ','). |
Lastname | No | 30 characters | Customer's last name. |
Firstname | No | 30 characters | Customer's first name. |
Middlename | No | 30 characters | Customer's middle name. |
Yes | 128 characters | Customer's e-mail. | |
City | No | 30 characters | Customer's address city. |
Street | No | 30 characters | Customer's address street. |
House | No | 18 characters | Customer's address house |
Building | No | 10 characters | Customer's address building. |
Apartment | No | 10 characters | Customer's address apartment. |
InfoLine* | No | 999 characters | Additional information – contract, commentary, etc. (the text from this field will be displayed to the customer upon payment). |
Date | No
| DDMMYYYY HHMMSS | Date of the register |
*For Info in SSIS nesting is allowed, one line should not exceed 999 characters, all together 2000.
The first line of the file should list the names of the parameters, the next lines should list their values. Data delimiter is semicolon. The currency is always Belarusian rubles BYN.
Example data in a file
MERCHANT_ID;PERSONALACCOUNT;DEBT;SURNAME;FIRSTNAME;EMAIL;INFOLINE 500069;DFG4567;100.01;Testov;Test;test@assist.by;contract 454566
Transfer of a file with a register of current personal accounts is carried out by agreement with the merchant at a certain frequency or upon request.
If, when making an advance payment, the personal account number is not exist in the register of current SSIS personal accounts in IPS Assist, the payment will be completed with an error.
At the request of the merchant, using the “Enable to pay for the arbitrary personal account in SSIS” setting, the IPS Assist technical support service can make enable payment for such personal accounts, at the same time with payment, the personal account will be added into the register of current SSIS personal accounts in IPS Assist automatically.
The prepared file with the register can be downloaded in the “ Customers ” section in the IPS Assist Personal Account.
Advance payments with customer verification on the merchant side
The merchant can organize replenishment of the client’s personal wallet through SSIS. The customer of the merchant will be able to use the wallet funds for subsequent payment of the order. To identify a customer, you can use a phone number, email address or other client ID. Verification is carried out using a pre-agreed ID (the customer must know what exactly needs to be used as an ID on the SSIS side to start top up his wallet).
Payment is carried out as follows:
- the customer finds the merchant in the SSIS catalog and enters his ID;
- SSIS sends a request to IPS Assist with the specified customer ID;
- IPS Assist sends a request to the merchant asking whether it has a customer with this ID;
- the customer specifies the amount to top up the wallet and begins the payment process through SSIS;
- SSIS sends a request to IPS Assist, then payment is made according to the existing advance payment scenario (the order number is generated automatically), the customer table is not used if there is verification from the merchant;
- after payment is made through SSIS, IPS Assist sends the authorization result to the merchant server with the customer ID and credit amount, the order/operation number in a result allows you to exclude duplicates on the merchant side.
To ensure client verification, the following verification service must be implemented on the merchant side:
Authorization: | login/password in the request body or BasicAuth - based on login/password in the request header |
Request: | HTTP POST |
Data transmission format: | JSON |
Request parameters
Parameter | Mandatory field | Format | Description |
account | Yes | String | Customer ID (personal account number) |
login | No | String | Authentication login |
password | No | String | Authentication password |
amount | No | Number | Amount (value 0 is sent in the request) |
Merchant server response
- HTTP 200 if the request was processed successfully. The response must contain the following fields:
Parameter | Mandatory field | Description | |
status | Yes | Processing status:
| |
amount | No | Optional block with information on the amount. | |
editable | Yes | «editable»: <bool - permission to edit amount> | |
arrears | Yes | «arrears»: <number, amount of debt> | |
min | No | «min»: <number, minimum amount>, makes sense only if editable=true, if editable=false the field is ignored. | |
max | No | «max»:<number, maximum amount>, makes sense only if editable=true, if editable=false the field is ignored. | |
accountInfo | No | Optional block of parameters with information about the customer, all parameters are of string type up to 30 characters long. | |
| fName | No | «fName»: <First name> |
lName | No | «lName»: <Last name> | |
mName | No | «mName”: <Middle name> | |
addressInfo | No | Optional parameter block with customer address. | |
| city | No | «city»: <City> - string up to 30 characters long. |
street | No | «street»: <Street> - string up to 30 characters long. | |
house | No | «house»: <House> - string up to 10 characters long. | |
building | Нет | «building»: <Building> - string up to 10 characters long. | |
apartment | Нет | «apartment»: <Apartment> - string up to 10 characters long. |
- HTTP 400 in case of incorrect input parameters. The response must contain the following fields:
status - string: "Error";
errorMessage - string: error description text; - HTTP 401 Unauthorized request (authorization failed):
status - string: "Error";
errorMessage - string: error description text; - HTTP 403 in case of problems with request execution. The response must contain the following fields:
status - string: "Error";
errorMessage - string: error description text.
Example of a request to a web service:
{"account":"TEST400_1","login":"test","password":"test1","amount":0}
Example of a successful response:
{{ "status":"Ok", "amount" : {"editable": true, "arrears": 100.00, "min": 1.00, "max":100.00} , "accountInfo" : {"fName" : "First name","lName": "Last name","mName": "Middle name"} , "addressInfo" : {"city": "City","street": "Street","house": 8,"building":"2","apartment":"34"} }}
An example of a response with an error:
{"status":"Error","errorMessage":"error 400 description text"}
An example of a response if there is no personal account:
{"status":"NotFound","errorMessage":"account not found"}
Payment notifications
To notify the merchant about the payment result in real time, the IPS Assist system provides a service for synchronously sending payment results to the merchant server. After the buyer completes payment for the order (using a bank card or one of the of electronic cash payment means), a message with payment parameters is sent to the merchant server using the HTTP POST or SOAP method.
You can set up sending in your Personal account by specifying the URL for sending results, protocol type (POST or SOAP), signature type and secret word.
After activating and configuring the service, the results of operations (payments, confirmations, cancellations - depending on the settings) will be sent to the merchant server. The results of payment transactions completed due to a timeout are not sent.
In the results of transactions for advance payments sent using the service, the personalaccount parameter is added (by request to the support service support@belassist.by) so that the merchant could determine to which personal account the payment was made.
Read more about sending payment results to the merchant server in the corresponding section of the documentation.
Attention! If a merchant receives daily registers of completed transactions from IPS Assist, for such registers it is also possible to indicate personal accounts in SSIS for which payments were made (if the merchant has advance payments). To configure such registries, you should contact IPS Assist technical support service (support@belassist.by).