To transfer the encrypted payment data block send a request to the IPS Assist server via HTTP POST method (n UTF-8 coding).
The request URL for transfer the encrypted payment data block:
https://<SERVER_NAME>/pay/tokenpay.cfm ,
As <SERVER_NAME> you should use the received from support service (support@assist.ru) value as the domain name.
List of request parameters:
Parameter | Mandatory field | Adopted values | Default value | Description |
Merchant_ID | Yes | Number | The enterprise identifier in IPS Assist | |
Login | Yes | 8-20 characters | Login in IPS Assist (Latin letters, digits and symbol _) | |
Password | Yes | 8-20 characters | Password in IPS Assist (Latin letters and digits) | |
OrderNumber | Yes | 128 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 | No | 3 characters | Currency of legal entity/enterprise | Code of currency of the OrderAmount |
OrderComment | No | 4000 characters | Comment. | |
Delay | No | 0 – one-stage operation | 0 | Attribute of a bankcard authorization for the double-stage operation mode. Attention! If you want to use the double-stage payment mechanism, you should first consult with the support service staff (support@assist.ru). |
Language | No | RU – Russian, | Language of legal entity/enterprise | Language of authorized pages |
ClientIP | No | Maximum of 15 digits, 4 delimiters «.» | IP-address of the customer. | |
TokenType | No | 1 – Apple Pay; | 1 | Payment Token Type Identifier 5 - payment token Assist is used for CIT COF operations |
PaymentToken | Yes | JSON | For token types 1-3 and 6 - provider payment token (Apple Pay, Google Pay, Samsung Pay, Mir Pay). For Assist payment token (token type 5) - {"Token": "<UUID>", "CustomerNumber": "<CustomerNumber>"} | |
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. |
isConvert | No | 0 – do not convert to the base currency | 1 | Currency conversion indicator |
Format | No | 4 – SOAP | 5 | Results format. |
Signature | No | String | The string is joined from the following order parameters: Merchant_ID;OrderNumber;OrderAmount;OrderCurrency with semicolon as delimiter. 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.
| |
RecurringIndicator | No | 1 –recurring payment | 0 | Recurring payment indicator |
RecurringMinAmount | No/Yes | Number, 15 digits, two digits after the delimiter (delimiter '.') | Minimum payment amount for recurring payments | |
RecurringMaxAmount | No/Yes | Number, 15 digits, two digits after the delimiter (delimiter '.') | Maximum payment amount for recurring payments | |
RecurringPeriod | No/Yes | 10 digits number | Recurring interval in days | |
RecurringMaxDate | No/Yes | Date in string representation DD.MM.YYYY | Finish date of recurring payments | |
Chequeitems | No/Yes1 | String in JSON-format | Cheque items according to the document “Payment with cheque”. | |
GenerateReceipt | No | 0 or 1 | 1 | Permission to generate of a fiscal receipt. If the value of parameter is 0, the generation of a fiscal receipt is prohibited for this order. |
Tax | No | 10 characters | Parameter is determined by the “Default tax rate” option of the merchant and used in the mode without transfer of the cheque items (the entire amount must be paid with one rate). | |
ReceiptLine | No | 128 characters | Parameter is determined by the “Default text of cheque item” option of the merchant and used in the mode without transfer of the cheque items. | Text description of the cheque item, if the cheque has one single item. |
FPMode | No | Number | Parameter is determined by the “Default payment method” option of the merchant and used in the mode without transfer of the cheque items. | |
TaxationSystem | No/Yes2 | Number | From the merchant’s or CRE settings |
1The cosist of the cheque (fields with the name, price per unit of product, tax rate and payment method for each item) is determined according to the following rules.
- If the request contains the ChequeItems structure (see the document “Payment with a cheque”), then a cheque is generated with the number of items according to the number of rows passed to ChequeItems, the parameters must be specified in each item:
- product и/или name;
- price;
- quantity;
- amount;
herewith:
the name of each item is built as the combination of the product and name parameters, separated by a space (if both are transferred) or as one of the product or name parameters, respectively (if only one is transferred);
if the Tax or FPmode parameters are not transferred in items, then they can be transferred in the request parameters (in this case, the values of these parameters will be the same for all cheque items transferred to ChequeItems);
if the Tax or FPmode parameters are not transferred in the request parameters, then their values are taken from the merchant settings (the values of these parameters will be the same for all cheque items transferred to ChequeItems);
if the merchant settings for these parameters are missing, the request processing ends with an error (there is not enough data to perform the operation).
2.If the request does not contain the CheckItems structure, then a cheque is generated with one item, in which:
- the item name is taken from the ReceiptLine parameter, if it is transferred in the request; if the ReceiptLine parameter is not transferred in the request, then the item name is taken from the merchant settings; if the merchant settings for these parameters are missing, then the name "Payment for the order" is used for the name;
- the unit price of product is taken from the request parameter Amount;
- the quantity is always equal 1;
if the Tax or FPmode parameters are not transferred in the request parameters, then their values are taken from the merchant settings;
if the merchant settings for these parameters are missing, the request processing ends with an error (there is not enough data to perform the operation).
2If the merchant uses several tax systems, the transfer of this parameter becomes mandatory.
The list of response parameters:
Name | Description |
Order parameters | |
ordernumber | Order number |
billnumber | Unique order number in IPS Assist |
testmode | Test mode |
ordercomment | Comment |
orderamount | Original amount of order |
ordercurrency | Original currency of order |
firstname | Payer's first name |
lastname | Payer's last name |
middlename | Payer's middle name |
Payer's e-mail | |
orderdate | Date of order (GMT) |
orderstate | Order status |
packetdate | Request issue date (GMT) |
signature | · For signature type 'MD5' - empty · For signature type 'PGP' – value X signed by secured key of IPS Assist, BASE64 encoded |
checkvalue | uppercase(md5(uppercase(md5(SALT) + md5(Х)))), where SALT – secret word ; Х – result of the following parameters string concatenation merchant_id, ordernumber, orderamount, ordercurrency, orderstate ( without delimiters) + means string concatenation |
Operation parameters | |
billnumber | Extended format of Billnumber: billnumber.<operation number> |
operationtype | Operation type |
operationstate | Operation status |
amount | Operation amount |
currency | Currency of operation |
ipaddress | Payer's IP-address |
clientip | Client's IP-address |
meantype_id | Payment means ID |
meantypename | Type of payment means |
meansubtype | Payment means subtype |
meannumber | Number of payment means |
cardholder | Payment means holder |
issuebank | Name of issue bank |
bankcountry | Country of issue bank |
responsecode | Response code |
message | Operation result message |
customermessage | Result message for a customer |
recommendation | Recommendation |
approvalcode | Authorization code |
protocoltypename | Protocol |
processingname | Processing name |
operationdate | Operation date and time(GMT) |
authresult | 3Ds authorization result (Y – success, N - fail, A - Attempt, U – unknown) |
authrequired | The card involvement in 3Ds check result (1 – involved, 0 – not involved, -1 – unknown, null – error appear during involvement check) |
slipno | Financial transaction identifier |
firstcode1 | The first code of automated interfaces error |
secondcode1 | The second code of automated interfaces error |
continueurl2 | The address to redirect to the authentication page for the buyer |
1The parameters firstcode and secondcode take the values "3" and "115", respectively, when a CVC2 enter is required; and if additional 3D-Secure authentication is required without entering a CVC2, the values of these parameters are “0”; the response code AS110 is given also in this case.
2The parameter is given only if CVC2 enter or additional 3D-Secure authentication is required, in which case the buyer should be redirected to the continueurl page to continue payment.
Attention! Please, note that several operations can be created within one order (payment, payment confirmation, cancellation). Furthermore, there can be several payment operations within one order, if some of them were unsuccessful. The order can have the only one successful payment operation. Thus there can be several enclosed operations within one order number in the response to a request for the operations results.
Attention! The testmode value of response has to be checked. If the payment was made in test mode (testmode = 1), then the shipment of goods or providing of services for the current request is not required.
An example of a request result in JSON format if the customer used a tokenized card:
{"order":[
{
"ordernumber":"26012015_4"
,"billnumber":"5899110210668265"
,"testmode":"0"
,"ordercomment":"test payment"
,"orderamount":"24.00"
,"ordercurrency":"RUB"
,"firstname":""
,"lastname":""
,"middlename":""
,"email":""
,"orderdate":"26.01.2015 17:25:39"
,"orderstate":"Timeout"
,"fraud_state":""
,"fraud_reason":""
,"checkvalue":"85C6C974AADC1CADFCFD195730ED090B"
,"operations":[
{"billnumber":"5899110210668265.1"
,"operationtype":"100"
,"operationstate":"In Process"
,"amount":"24.00"
,"currency":"RUB"
,"clientip":"10.20.10.85"
,"ipaddress":"0.0.0.0"
,"meantype_id":"61"
,"meantypename":"In Process"
,"meansubtype":""
,"meannumber":""
,"cardholder":""
,"issuebank":"UNKNOWN"
,"bankcountry":"UNKNOWN"
,"responsecode":"AS200"
,"message":""
,"customermessage":"
,"recommendation":""
,"approvalcode":""
,"protocoltypename":"NET"
,"processingname":""
,"operationdate":"26.01.2015 17:25:39"
,"authresult":""
,"authrequired":""
,"slipno":""}
]
}
],
"packetdate":"26.01.2015 18:16:19"
}
An example of a request result in JSON format if the customer used a non-tokenized card:
{"order":[
{
"ordernumber":"2019.07.01-1226",
"billnumber":"516009019047110",
"testmode":"0",
"ordercomment":"Test 4 mode",
"orderamount":"101.45",
"ordercurrency":"RUB",
"firstname":"",
"lastname":"",
"middlename":"",
"email":"",
"orderdate":"01.07.2019 15:31:16",
"orderstate":"In Process",
"fraud_state":""
"fraud_reason":""
"checkvalue":"85C6C974AADC1CADFCFD195730ED090B"
"operations":[
{"billnumber":"516009019047110.1",
"operationtype":"100",
"operationstate":"New",
"amount":"101.45",
"currency":"RUB",
"clientip":"10.20.10.66",
"ipaddress":"127.0.0.1",
"meantype_id":"1",
"meantypename":"VISA",
"meansubtype":"Classic",
"meannumber":"411111****1111",
"cardholder":"N/A",
"cardexpirationdate":"12/24",
"issuebank":"New Assist Bank",
"bankcountry":"Россия",
"responsecode":"AS300",
"message":"",
"customermessage":"", "
"recommendation":"",
"approvalcode":"",
"protocoltypename":"NET",
"processingname":"UCS",
"operationdate":"01.07.2019 15:31:18",
"authresult":"",
"authrequired":"",
"slipno":""}
]
}
],
"packetdate":"26.01.2015 18:16:19",
"firstcode":"3",
"secondcode":"115",
"continueurl":"https://<SERVER_NAME>/pay/pay.cfm?CFSID=LiRNMzMiSFc3Wy0nWFdaQCJYTiQgCg%3D%3D"
}
In case of successful payment the return code responsecode is equal to AS000 value.
In case of unsuccessful payment the responsecode is one of AS100-AS998 values (except AS110 code that is returned when 3-D Secure authorization required).
If the request can't be processed the firstcode and secondcode parameters have non-zero values.