To pay with a token, you need to send a request to the IPS Assist server in JSON format (swagger description: https://docs.belassist.by/swagger/ ).
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 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 |
Order Comment | No | 4000 characters | Comment. | |
Delay | No | 0 – one-stage operation | 0 | Attribute of a bankcard authorization for the double-stage operation mode. |
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 |
PaymentToken | Yes | JSON | For token types 1-3 - provider payment token (Apple Pay, Google Pay; Samsung Pay). | |
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 - do not convert to the base currency if possible 2 – always 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 |
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":"BYN"
,"firstname":""
,"lastname":""
,"middlename":""
,"email":""
,"orderdate":"26.01.2015 17:25:39"
,"orderstate":"In Process"
,"fraud_state":""
,"fraud_reason":""
,"checkvalue":"85C6C974AADC1CADFCFD195730ED090B"
,"operations":[
{"billnumber":"5899110210668265.1"
,"operationtype":"100"
,"operationstate":"In Process"
,"amount":"24.00"
,"currency":"BYN"
,"clientip":"10.20.10.85"
,"ipaddress":"0.0.0.0"
,"meantype_id":"61"
,"meantypename":"SamsungPay"
,"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":"BYN",
"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":"BYN",
"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":"BANK",
"bankcountry":"Россия",
"responsecode":"AS300",
"message":"",
"customermessage":"", "
"recommendation":"",
"approvalcode":"",
"protocoltypename":"NET",
"processingname":"NAME",
"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.
