Features of SSIS payments

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.

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 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:

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

*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

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:

* 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:

* 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:

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.

*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:

Request parameters

Merchant server response

• HTTP 200 if the request was processed successfully. The response must contain the following fields:

• 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.

Back on top