IPS Assist allows merchants to use additional opportunities to attract customers in the form of advertising campaigns. Merchants can conduct advertising campaigns aimed at promoting certain goods (services) independently (or together with banks). By purchasing such goods (services) the customer is provided with an agreed discount, subject to payment with a card of a certain type. The promotion may also include prize drawings for customers depending on the number of purchases in certain stores and payment for these purchases with certain types of cards. Promotions have time limits set by the organizer.
The payment page displays the organizer's information about the discount or promotion and its conditions. To participate in the promotion, the buyer's consent is required. As part of the promotion, informational letters may be sent to the buyer after payment.
IPS Assist provides merchants with the opportunity to organize three types of promotions:
Promotions
By a promotion the merchant provides a discount on its side if the buyer pays for a product (service) with a card of a certain bank and/or a certain type.
By making a payment under a promotion:
The merchant sends the payment amount in the payment request, already taking into account the discount.
IPS Assist checks the buyer's card for participation in the promotion:
- if the promotion is valid at the time of payment and the card meets the terms of the promotion, then IPS Assist makes a payment for the amount (with a discount) transferred by the merchant;
- if the promotion is not valid at the time of payment or the card does not meet the terms of the promotion, then the payment is not made and an error message is displayed.
The merchant organizes on its side the possibility of payment for the buyer with a discount (for the promotion) or without a discount (for cards not participating in the promotion), if necessary.
Also, to pay for an order under a promotion, you need to send the additional parameter “PROMONAME” in the request. The value of the parameter is the name of the specific promotion. The unique name of the promotion is generated by the IPS Assist technical support service and transferred to the merchant (the name can also be chosen together with the merchant).
The main part of the promotion settings is performed on the IPS Assist side. To do this, the merchant should inform the technical support department of IPS Assist about the exact values of the promotion parameters:
time of action;
types of cards that participate in the advertising campaign.
Discounts
A discount may be provided as part of a promotion if the buyer pays for a product (service) with a card of a certain bank and/or a certain type.
The order amount for payment with a discount is calculated on the IPS Assist side according to the approved rules of the promotion.
The discount can be without sending the “PROMONAME” parameter or with sending the “PROMONAME” parameter. The value of the parameter is the name of the specific discount promotion. The unique name of the promotion is generated by the IPS Assist technical support service and transferred to the merchant (the name can also be chosen together with the merchant).
At the same time, only one discount with the send of the “PROMONAME” parameter is possible for the merchant. If the parameter is sent, but the card does not meet the conditions, the payment will be made for the full amount without a discount.
There can be different discounts for different conditions without sending the “PROMONAME” parameter. If the buyer’s card fits for several discounts at once, then the discount is applied according to the approved rules of the promotion.
To use a discount, it is necessary to develop special payment page templates or modify individual templates. Payment pages should display information about discount conditions.
The main part of the discount settings is performed on the IPS Assist side. To do this, the merchant should inform the technical support department of IPS Assist about the exact values of the discount parameters:
- type of discount with or without sending the “PROMONAME” parameter;
- discount duration;
- message text for buyer;
- discount amount as a percentage and rounding rules for calculating the discount amount, as well as the maximum possible discount amount;
- rules for choosing a discount if there are several different promotions with discounts (summing discounts or using the maximum of several);
- types of cards that participate in the promotion.
It should be borne in mind that payment with a discount in IPS Assist will consist of two operations: one real for the amount of the order minus the discount and the second virtual for the amount of the discount. Both operations will be displayed in the merchant’s Personal account, as well as in the responses of the payment results web services. The receipt for the buyer will indicate the total amount of the order, the amount paid and the discount.
Examples of responses to a request to receive operations results by order number
In XML format:
<?xml version='1.0' encoding='utf-8' standalone='yes'?>
<!DOCTYPE result [
<!ATTLIST result
firstcode CDATA #REQUIRED
secondcode CDATA #REQUIRED
count CDATA #REQUIRED>
<!ELEMENT result (order*)>
<!ELEMENT order (ordernumber?,billnumber?,testmode?,ordercomment?,orderamount?,ordercurrency?,firstname?,lastname?,middlename?,email?,orderdate?,orderstate?,packetdate?,signature?,checkvalue?,operation*)>
<!ELEMENT ordernumber (#PCDATA)>
<!ELEMENT billnumber (#PCDATA)>
<!ELEMENT testmode (#PCDATA)>
<!ELEMENT ordercomment (#PCDATA)>
<!ELEMENT orderamount (#PCDATA)>
<!ELEMENT ordercurrency (#PCDATA)>
<!ELEMENT firstname (#PCDATA)>
<!ELEMENT lastname (#PCDATA)>
<!ELEMENT middlename (#PCDATA)>
<!ELEMENT email (#PCDATA)>
<!ELEMENT orderdate (#PCDATA)>
<!ELEMENT orderstate (#PCDATA)>
<!ELEMENT packetdate (#PCDATA)>
<!ELEMENT signature (#PCDATA)>
<!ELEMENT checkvalue (#PCDATA)>
<!ELEMENT operation
(billnumber?,operationtype?,operationstate?,amount?,currency?,clientip?,ipaddress?,meantype_id?,meantypename?,meansubtype?,meannumber?,cardholder?,issuebank?,bankcountry?,responsecode?,message?,customermessage?,recommendation?,approvalcode?,protocoltypename?,processingname?,operationdate?,authresult?,authrequired?,rrn?,extrrn?)>
<!ELEMENT operationtype (#PCDATA)>
<!ELEMENT operationstate (#PCDATA)>
<!ELEMENT amount (#PCDATA)>
<!ELEMENT currency (#PCDATA)>
<!ELEMENT clientip (#PCDATA)>
<!ELEMENT ipaddress (#PCDATA)>
<!ELEMENT meantype_id (#PCDATA)>
<!ELEMENT meantypename (#PCDATA)>
<!ELEMENT meansubtype (#PCDATA)>
<!ELEMENT meannumber (#PCDATA)>
<!ELEMENT cardholder (#PCDATA)>
<!ELEMENT issuebank (#PCDATA)>
<!ELEMENT bankcountry (#PCDATA)>
<!ELEMENT responsecode (#PCDATA)>
<!ELEMENT message (#PCDATA)>
<!ELEMENT customermessage (#PCDATA)>
<!ELEMENT recommendation (#PCDATA)>
<!ELEMENT approvalcode (#PCDATA)>
<!ELEMENT protocoltypename (#PCDATA)>
<!ELEMENT processingname (#PCDATA)>
<!ELEMENT operationdate (#PCDATA)>
<!ELEMENT authresult (#PCDATA)>
<!ELEMENT authrequired (#PCDATA)>
<!ELEMENT rrn (#PCDATA)>
<!ELEMENT extrrn (#PCDATA)>]>
<result firstcode='0' secondcode='0' count='1'>
<order>
<ordernumber>2022.07.11-6</ordernumber>
<billnumber>5732614256223423</billnumber>
<testmode>0</testmode>
<ordercomment></ordercomment>
<orderamount>100.00</orderamount>
<ordercurrency>BYN</ordercurrency>
<firstname>Test</firstname>
<lastname>Testov</lastname>
<middlename>T.</middlename>
<email>test@assist.by</email>
<orderdate>11.07.2022 07:23:02</orderdate>
<orderstate>Approved</orderstate>
<packetdate>11.07.2022 07:41</packetdate>
<signature></signature>
<checkvalue>65A46731208432C4018D42091E8E4F35</checkvalue>
<operation>
<billnumber>5732614256223423.1</billnumber>
<operationtype>100</operationtype>
<operationstate>Success</operationstate>
<amount>90.00</amount>
<currency>BYN</currency>
<clientip>81.211.118.98</clientip>
<ipaddress>0.0.0.0</ipaddress>
<meantype_id>1</meantype_id>
<meantypename>VISA</meantypename>
<meansubtype>Classic</meansubtype>
<meannumber>411111****1111</meannumber>
<cardholder>TEST TESTOV</cardholder>
<cardexpirationdate>12/25</cardexpirationdate>
<issuebank>New Assist Bank</issuebank>
<bankcountry>Russia</bankcountry>
<responsecode>AS000</responsecode>
<message> </message>
<customermessage></customermessage>
<recommendation></recommendation>
<approvalcode>X26591</approvalcode>
<protocoltypename>NET</protocoltypename>
<processingname>BPCBel</processingname>
<operationdate>11.07.2022 07:23:02</operationdate>
<authresult>Y</authresult>
<authrequired>1</authrequired>
<slipno></slipno>
<threedsdata>
<version>1.0</version>
<alphaauthresult>Y</alphaauthresult>
<challenge>C</challenge>
<eci>5</eci>
</threedsdata>
</operation>
<operation>
<billnumber>5732614256223423.2</billnumber>
<operationtype>100</operationtype>
<operationstate>Success</operationstate>
<amount>10.00</amount>
<currency>BYN</currency>
<clientip>81.211.118.98</clientip>
<ipaddress>0.0.0.0</ipaddress>
<meantype_id>21</meantype_id>
<meantypename>Discount</meantypename>
<meansubtype></meansubtype>
<meannumber></meannumber>
<cardholder></cardholder>
<cardexpirationdate></cardexpirationdate>
<issuebank>UNKNOWN</issuebank>
<bankcountry>UNKNOWN</bankcountry>
<responsecode>AS000</responsecode>
<message> </message>
<customermessage></customermessage>
<recommendation></recommendation>
<approvalcode></approvalcode>
<protocoltypename></protocoltypename>
<processingname>Disc</processingname>
<operationdate>11.07.2022 07:23:08</operationdate>
<authresult></authresult>
<authrequired></authrequired>
<slipno></slipno>
<threedsdata>
<version></version>
<alphaauthresult></alphaauthresult>
<challenge></challenge>
<eci>7</eci>
</threedsdata>
</operation>
</order>
</result>
In SOAP format:
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://www.paysecure.ru/ws/">
<soapenv:Body>
<ws:orderresultResponse>
<orderresult>
<order>
<ordernumber>2022.07.11-6</ordernumber>
<billnumber>5732614256223423</billnumber>
<testmode>0</testmode>
<ordercomment></ordercomment>
<orderamount>100.00</orderamount>
<ordercurrency>BYN</ordercurrency>
<firstname>Test</firstname>
<lastname>Testov</lastname>
<middlename>T.</middlename>
<email>test@assist.by</email>
<orderdate>11.07.2022 07:23:02</orderdate>
<orderstate>Approved</orderstate>
<packetdate>11.07.2022 07:42</packetdate>
<signature></signature>
<checkvalue>65A46731208432C4018D42091E8E4F35</checkvalue>
<operation>
<billnumber>5732614256223423.1</billnumber>
<operationtype>100</operationtype>
<operationstate>Success</operationstate>
<amount>90.00</amount>
<currency>BYN</currency>
<clientip>81.211.118.98</clientip>
<ipaddress>0.0.0.0</ipaddress>
<meantype_id>1</meantype_id>
<meantypename>VISA</meantypename>
<meansubtype>Classic</meansubtype>
<meannumber>411111****1111</meannumber>
<cardholder>TEST TESTOV</cardholder>
<cardexpirationdate>12/25</cardexpirationdate>
<issuebank>New Assist Bank</issuebank>
<bankcountry>Russia</bankcountry>
<responsecode>AS000</responsecode>
<message> </message>
<customermessage> </customermessage>
<recommendation></recommendation>
<approvalcode>X26591</approvalcode>
<protocoltypename>NET</protocoltypename>
<processingname>BPCBel</processingname>
<operationdate>11.07.2022 07:23:02</operationdate>
<authresult>Y</authresult>
<authrequired>1</authrequired>
<slipno></slipno>
<threedsdata>
<version>1.0</version>
<alphaauthresult>Y</alphaauthresult>
<challenge>C</challenge>
<eci>5</eci>
</threedsdata>
</operation>
<operation>
<billnumber>5732614256223423.2</billnumber>
<operationtype>100</operationtype>
<operationstate>Success</operationstate>
<amount>10.00</amount>
<currency>BYN</currency>
<clientip>81.211.118.98</clientip>
<ipaddress>0.0.0.0</ipaddress>
<meantype_id>21</meantype_id>
<meantypename>Discount</meantypename>
<meansubtype></meansubtype>
<meannumber></meannumber>
<cardholder></cardholder>
<cardexpirationdate></cardexpirationdate>
<issuebank>UNKNOWN</issuebank>
<bankcountry>UNKNOWN</bankcountry>
<responsecode>AS000</responsecode>
<message> </message>
<customermessage> </customermessage>
<recommendation></recommendation>
<approvalcode></approvalcode>
<protocoltypename></protocoltypename>
<processingname>Disc</processingname>
<operationdate>11.07.2022 07:23:08</operationdate>
<authresult></authresult>
<authrequired></authrequired>
<slipno></slipno>
<threedsdata>
<version></version>
<alphaauthresult></alphaauthresult>
<challenge></challenge>
<eci>7</eci>
</threedsdata>
</operation>
</order>
</orderresult>
</ws:orderresultResponse>
</soapenv:Body>
In JSON format:
{
"orderresult": {
"orders": [
{
"operations": [
{
"customermessage": " ",
"message": " ",
"operationdate": "11.07.2022 07:23:02",
"operationtype": 100,
"authrequired": "1",
"cardexpirationdate": "12/25",
"operationstate": "Success",
"threedsdata": {
"version": "1.0",
"eci": "5",
"alphaauthresult": "Y",
"challenge": "C"
},
"recommendation": "",
"processingname": "BPCBel",
"meannumber": "411111****1111",
"meantype_id": 1,
"authresult": "Y",
"clientip": "81.211.118.98",
"ipaddress": "0.0.0.0",
"amount": 90,
"responsecode": "AS000",
"meantypename": "VISA",
"protocoltypename": "NET",
"bankcountry": "Russia",
"cardholder": "TEST TESTOV",
"approvalcode": "X26591",
"slipno": "",
"issuebank": "New Assist Bank",
"currency": "BYN",
"billnumber": "5732614256223423.1",
"meansubtype": "Classic"
},
{
"customermessage": " ",
"message": " ",
"operationdate": "11.07.2022 07:23:08",
"operationtype": 100,
"authrequired": "",
"cardexpirationdate": "",
"operationstate": "Success",
"threedsdata": {
"version": "",
"eci": "7",
"alphaauthresult": "",
"challenge": ""
},
"recommendation": "",
"processingname": "Disc",
"meannumber": "",
"meantype_id": 21,
"authresult": "",
"clientip": "81.211.118.98",
"ipaddress": "0.0.0.0",
"amount": 10,
"responsecode": "AS000",
"meantypename": "Discount",
"protocoltypename": "",
"bankcountry": "UNKNOWN",
"cardholder": "",
"approvalcode": "",
"slipno": "",
"issuebank": "UNKNOWN",
"currency": "RUB",
"billnumber": "5732614256223423.2",
"meansubtype": ""
}
],
"testmode": 0,
"customer": {
"lastname": "Testov",
"firstname": "Test",
"middlename": "T.",
"email": "test@assist.by"
},
"orderdate": "11.07.2022 07:23:02",
"packetdate": "11.07.2022 07:29",
"orderamount": 100,
"ordercomment": "",
"ordercurrency": "BYN",
"orderstate": "Approved",
"signature": "",
"checkvalue": "65A46731208432C4018D42091E8E4F35",
"billnumber": "5732614256223423",
"ordernumber": "2022.07.11-6"
}
]
}
An example of a discount operation authorization result package sent to the merchant server
11.07.2022 07:15:55 Request Operation_ID:6000929 TO URL:https://<SERVER-NAME>/merchant-services/service Params: merchant_id:732614;ordernumber:2022.07.11-5;billnumber:5732614256223415.2;testmode:0;ordercomment:;orderamount:100.00;ordercurrency:BYN;amount:10.00;currency:BYN;rate:1;firstname:Test;lastname:Testov;middlename:T.;email:null@assist.by;clientip:81.211.118.98;ipaddress:0.0.0.0;meantype_id:21;meantypename:Discount;meansubtype:;meannumber:;cardholder:;cardexpirationdate:;issuebank:UNKNOWN;bankcountry:UNKNOWN;orderdate:11.07.2022 07:15:46;orderstate:Approved;responsecode:AS000;message:;customermessage:;recommendation:SUCCESSFUL AUTHORIZATION;approvalcode:;protocoltypename:;processingname:Discount;operationtype:100;operationdate:11.07.2022 07:15:51;authresult:;authrequired:;slipno:;packetdate:11.07.2022 07:15:55;signature:;checkvalue:F0D84B730CCF85C264A9C2289EEC9113;token:;version:;alphaauthresult:;challenge:;eci:7;
An example of a payment operation authorization result package sent to the merchant server
11.07.2022 07:23:15 Request Operation_ID:6000930 TO URL:https:// URL:https://<SERVER-NAME>/merchant-services/service Params: merchant_id:732614;ordernumber:2022.07.11-6;billnumber:5732614256223423.1;testmode:0;ordercomment:;orderamount:100.00;ordercurrency:BYN;amount:90.00;currency:BYN;rate:1;firstname:Test;lastname:Testov;middlename:T.;email:null@assist.by;clientip:81.211.118.98;ipaddress:0.0.0.0;meantype_id:1;meantypename:VISA;meansubtype:Classic;meannumber:411111****1111;cardholder:TEST TESTOV;cardexpirationdate:12/25;issuebank:New Assist Bank;bankcountry:Russia;orderdate:11.07.2022 07:23:02;orderstate:Approved;responsecode:AS000;message:;customermessage:;recommendation:SUCCESSFUL AUTHORIZATION;approvalcode:X26591;protocoltypename:NET;processingname:BPCBel;operationtype:100;operationdate:11.07.2022 07:23:02;authresult:Y;authrequired:1;slipno:;packetdate:11.07.2022 07:23:15;signature:;checkvalue:7C8A939B29D3384F8DB6890452506A27;token:;version:1.0;alphaauthresult:Y;challenge:C;eci:5;
Promo games
Promotional games are promotions that provide prizes to customers based on the number of purchases at certain stores and payment of these purchases with certain types of cards. Prizes may include, for example, promotional codes, as well as certain goods or services.
The specific conditions of the promotional game are discussed by the merchant with the technical support service of IPS Assist; the merchant transfers the necessary data on the promotional game to the technical support department of IPS Assist for correct system configuration.
If the terms of the game require payment to several different merchants, then all these merchants participate in the promotional game equally, without any special features.
To pay for an order with the bayer participating in a promotional game, you need to send the additional parameter “PROMOGAME” in the request. The value of the parameter is the name of the specific promotional game. The unique name of the promotional game is generated by the IPS Assist technical support service and transferred to the merchant (the name can also be chosen together with the merchant). If the request does not contain the additional parameter “PROMOGAME”, by agreement with the merchant) on the IPS Assist side, you can configure the refusal of payment or acceptance of payment without participating in the game.
Unlike other types of promotions, by using promotional games, specific possibilities for implementing various functions of the promotional game are discussed with the merchant and, based on the results, all necessary settings are negotiated on the IPS Assist side and on the merchant side. The implementation of the results of promotional games in the form of prizes remains on the merchant’s side.
For the promotional game, it is necessary to develop special payment page templates or modify individual templates. Payment pages should display information about the game and its rules (or a link to them).
You should also develop special templates for letters to the buyer about the result of the payment with additional information about participation in the game.
