External system interacts with SOFI as an on-line client. SOFI provides SOAP interfaces which should be used. Data interchange is organized via HTTPS with trusted SSL certificates. Authorization with login/password is used.
The following root certificates have to be installed on the requester side for correct work with WEB-services:
- root certificate Thawte: Comodo: COMODO RSA Certification Authority (https://support.comodo.com/index.php?/Default/Knowledgebase/Article/View/969/108/root-comodo-rsa-certification-authority-sha-2);
- root certificate GlobalSign: GlobalSign Root CA R1 (https://www.globalsign.com/repository/ca-certificates/).
Before to start, check the presence of these certificates and add them if necessary.
API interface URL is https://afs-api.paysecure.ru/antifraudapi.
WSDL for SOAP protocol can be obtained by the following link: https://afs-api.paysecure.ru/antifraudapi?wsdl.
There are two possible modes of SOFI usage during checking a payment through the SOFI:
- The external system collects all possible data about payment operation and after that sends it to SOFI by calling SOAP procedure check and passing all the collected data. In this case SOFI uses all possible checking mechanisms to check the payment.
- The external system calls check several times passing the data in process of collection. Each new call of check should be performed with all collected at the moment data. Note that if in some future call of check some parameters are missed (that were passed before) then this data will be removed from the data pool, which SOFI uses for checking the payment.
After the decision of external system to authorize or reject the payment, the external system has to notify the SOFI about the decision by calling setPaymentStatus procedure. After this calling all calls of check will return the current fraud-status and SOFI don't perform any additional checks.
Procedure getFraudStatus can be used to receive the current fraud-status of the payment that was already checked by SOFI.
A merchant can be registered within the SOFI by calling setMerchantData procedure. This procedure can be also used to update a data of the merchant (when registered name or E-mail changes).
If a merchant which is indicated in a call of check procedure is not registered yet then SOFI automatically creates the merchant profile and notify the external system about this merchant profile creation. As a reaction on this notification the external system must update the merchant profile within the SOFI by calling the setMerchantData procedure.
If the payers make payments using web-pages, then it is desirable to place (on the web-page where payment verified via SOFI) the call of the following JavaScript code:
<script type="text/javascript">
window.collect_afs_data_func = function() {
try {
var url = "https://afs-api.paysecure.ru/antifraudapi/rest/afs_data_collector.js?outSystemId=...&outPaymentId=...";
var method = "GET";
var xhr = window.XMLHttpRequest ? new XMLHttpRequest() : new XDomainRequest();
if ("withCredentials" in xhr) {
xhr.open(method, url, true);
} else if (typeof XDomainRequest != "undefined") {
xhr = new XDomainRequest();
xhr.open(method, url);
} else {
xhr = null;
}
if (xhr) {
xhr.onreadystatechange=function() {
if (xhr.readyState==4 || xhr.readyState=="complete") {
try {
eval(xhr.responseText);
} catch (e) {alert(e);}
}
};
try {
xhr.withCredentials = true;
} catch (e) {
}
xhr.send('');
}
} catch (e) {
alert(e);
}
};
if (window.addEventListener) {
window.addEventListener('load', function(){window.collect_afs_data_func(); }, false);
} else if (window.attachEvent) {
window.attachEvent('onload', function(){window.collect_afs_data_func();});
}
</script>
Parameters outSystemId and outPaymentId should be assigned to the corresponding ID values (see table "Mandatory fields of CheckPaymentParams").
Payment check procedure
Payment check procedure name is check.
Input parameters
The only input parameter that is transmitted from external system for SOFI analysis of the payment transaction is parameter params, which is a data structure called CheckPaymentParams.
Mandatory fields of CheckPaymentParams
Required fields of CheckPaymentParams are transferred as simple data types (integer, string, boolean).
Mandatory fields of CheckPaymentParams
Field | Description | Type |
outPaymentId | Payment operation identity number, which is assigned to the operation within the external system. | Integer (15) |
outSystemId | External system ID. | Integer (15) |
outMerchantId | Merchant identity number (external merchant ID). | Integer (15). |
domainId | Application/service code. | Integer (15) |
paymentTypeId | Payment type. | Integer (15) Integer code from the table "Payment types". |
Payment types
Name | Код |
e-commerce | 1 |
MO/TO | 2 |
POS | 3 |
Optional fields of CheckPaymentParams
The optional fields also can be transferred via parameter.
When fields of CheckPaymentParams are passed to SOFI by several calls of check, the fields of CheckPaymentParams, which were provided in previous call of check should be also provided in the next call. Fields that are not known on the time of calling check are passed as null value.
If in some future calls of check some fields of CheckPaymentParams are missed (that were passed before) then this data will be removed from the data pool that SOFI uses for checking the payment.
Optional fields of CheckPaymentParams
Field | Description | Type |
paymentAttributes | Payment data (see table "Payment operation data" for details). | List of structures |
clientAttributes | Data of client browser, which is used for payment. | List of structures |
httpAttributes | Headers of HTTP-request from client browser to external system during the payment. | List of structures |
serverAttributes | Variables of environment. | List of structures |
timeOut | SOFI response time out (in milliseconds). If this parameter is not set then the default value 10 seconds is used. Negative value will indicate that there is no time-out. NOTE. There is a possibility to switch off the SOFI notification about fraud-status when time-out expired (by default SOFI sends notifications even if time-out expired). Please, contact the support team to change this behavior. | Integer |
sendNotification | True value enforces SOFI to mandatory notify the external system about payment fraud-status after the check finishes its work. By default notification is not send. | Logical (true, false) |
paymentStatus | Data for payment status change | Structure of data |
Stuctures in the fields descriptions of CheckPaymentParams
Structure | Description | Type |
name | Parameter name | Sting (case-insensitive) |
booleanValue | Filled when the parameter type is logical. | Logical (true, false) |
doubleValue | Filled when the parameter type is numerical. | Decimal |
stringValue | Filled when the parameter type is string. | String |
intValue | Filled when the parameter type is integer. | Integer |
dateValue | Filled when the parameter type is data. | Data |
Payment operation data (paymentAttributes)
Payment operation data
Field | Description | Type |
Meannumber | The encrypted card number1 has to be passed as following string: "IR_TOKEN=<irreversible token PAN> BIN=<6 first digits of PAN> POST==<4 last digits of PAN>". Alternatively, you can pass the payment mean number in unencrypted form, but this ability will be removed in the future. | String (70 chars) |
meanTypeGroup | Group of payment means: 1 - card (by default), 2 – E-wallet | Integer (1) |
meanType | Type of E-wallet (required for E-wallets). Available types of electronic wallets are presented in the table «Type of E-wallets». | String (3 chars) |
OutAmount | Payment amount in original currency | Decimal (15,2) |
OutCurrencyCode | Currency code (ISO 42 17) | String (3 chars) |
BillNumber | Bill number from external system | String (30 chars) |
OrderNumber | Order number for payment operation | String (128 chars) |
Customer Email | String (128 chars) | |
Firstname | Customer name | String (128 chars) |
Middlename | Customer middle name | String (70 chars) |
Lastname | Customer second name | String (70 chars) |
Regioncode | Customer region code | String (8 chars) |
Regionname | Customer region name | String (70 chars) |
City | City | String (70 chars) |
Countrycode | Country code (ISO 3166 alpha-2) | String (2 chars) |
Address | Customer postal address | String (256 chars) |
Postcode | Postal index | String (25 chars) |
Phone | Phone number | String (20 chars) |
Workphone | Work phone number | String (20 chars) |
Mobilephone | Mobile phone number | String (20 chars) |
Cardholder | Card-holder name | String (130 chars) |
Bankname | Issuer-Bank name | String (100 chars) |
Acquirer | Acquirer name (unique within the external system). | String (10 chars) |
Date | Payment data (UTC data (GMT-0) or GMT+ hour-offset). If it is not provided then current date is used. | Data |
Expiredate | Card expire date (month, year). UTC data (GMT-0) or GMT+ hour-offset when time is including. | Data |
BillingNumberTag | Type of billing number in favor of which the payment is made as cell phone number, contract number for communication services, etc. Currently, the following types of billing are available for activation: · YBIL (Yota billing); · MTSBelBlN (MTS Belarussia BillNumber); · MTSBelPhN (MTS Belarussia PhoneNumber); · MTTPhN (MTT Phone Number); · MTTTel (MTT Telecommunication); · MTTInt (MTT Internet). | String (10 chars) |
BillingNumber | Billing number in favor of which the payment is made. | String (10 chars) |
TwoStepSchema | Double stage payment (separate authorization and charge operations are performed). If it is not provided then single stage (one operation assumes authorization and charge is performed). | Logical (true, false) |
Additional fields for payments by American Express cards | ||
billingPostalCode | Customer postal index | String (9 chars) |
billingAddress | Customer postal address | String (20 chars) |
billingFirstName | Customer name | String (15 chars) |
billingLastName | Customer second name | String (30 chars) |
billingPhoneNumber | Customer phone number | String (10 chars) |
billingEMailAddress | Customer E-mail | String (60 chars) |
TestMode | Test payment indicator. | Logical (true, false) |
RecurringIndicator | Recurring payment indicator | Logical (true, false) |
usedCSC | Card Secure Code was used | Logical (true, false) |
3DSecAuthresult | 3DSecure authorization result (Y - success, N - fail, A - attempt, U –unknown) | String (1 char) |
AirData | XML with additional flight data (for air companies)2 | Text |
BookingData | XML with additional booking data3 | Text |
3DSecAuthrequired | Result of card 3dS involvement check (1 – involved, 0 – not involved, -1 – not-known, null – all rest) | Decimal (1) |
1To get access to the service for receiving irreversible token from ASSIST company, you have to contact technical support team (support@assist.ru).
Fields, which are highlighted by bold – are necessary for math methods of analysis. Underscored fieldss are important for the quality of math methods of analysis.
Type of E-wallets
E-wallet type | E-wallet name |
WM | WebMoney |
EP | EasyPay |
QW | QIWI |
QB | QIWIBeeline |
QM | QIWIMts |
QF | QIWIMegafon |
MB | Mobicon |
YM | YandexMoney |
2 XML format for additional flight-data:
<ad_pnr>
<pnrdate>...</pnrdate> <!-- datetime 8 -->
<email>...</email> <!-- varchar 128 -->
<language>...</language> <!-- varchar 5 -->
<phoneb>...</phoneb> <!-- varchar 32 (work)-->
<phone>...</phone> <!-- varchar 32 (personal)-->
<phonem>...</phonem> <!-- varchar 32 (mobile)-->
<airline_rec_loc>...</airline_rec_loc> <!-- varchar 16 (usually is Record_locator)-->
<record_locator>...</record_locator> <!-- varchar 16 (usually is PNR)-->
<traveler_id>...</traveler_id> <!-- varchar 16 (customer code)-->
<air_amount_1>...</air_amount_1> <!-- money 8 (amount in orig. currency)-->
<air_amount_2>...</air_amount_2> <!-- money 8 (amount in currency of payment)-->
<air_amount_with_serv_1>...</air_amount_with_serv_1> <!-- money 8 -->
<air_amount_with_serv_2>...</air_amount_with_serv_2> <!-- money 8 -->
<air_amount_without_tax_1>...</air_amount_without_tax_1> <!-- money 8 -->
<air_amount_without_tax_2>...</air_amount_without_tax_2> <!-- money 8 -->
<air_currency_code_1>...</air_currency_code_1> <!-- varchar 5 -->
<air_currency_code_2>...</air_currency_code_2> <!-- varchar 5 -->
<delivery_type>...</delivery_type> <!-- varchar 16 (code of delivery)-->
<agent_code>...</agent_code> <!-- varchar 16 (agency code)-->
<charge_type>...</charge_type> <!-- varchar 16 (agency code)-->
<ticket_number>...</ticket_number> <!-- varchar 14 (ticket number)-->
<restr_ticked_ind>...</restr_ticked_ind> <!-- varchar 1 (Restricted Ticked Indicator)-->
<add_field1>...</add_field1> <!-- varchar 255 (Positioned extended record)-->
<add_field2>...</add_field2> <!-- varchar 255 (Positioned extended record)-->
<number>...</number><!-- varchar 16 (pnr number)-->
<number>...</number><!-- varchar 16 (pnr number)-->
...
<segment> <!-- маршрут -->
<airline_code>...</airline_code> <!-- varchar 5 (company code)-->
<airline_name>...</airline_name> <!-- varchar 64 (company name)-->
<cabin>...</cabin> <!-- varchar 5 (class)-->
<flight_number>...</flight_number> <!-- varchar 16 (flight number)-->
<flight_time>...</flight_time> <!-- varchar 12 (flight time)-->
<itinerary_numb>...</itinerary_numb><!-- int 4 (direction number)-->
<orig_numb>...</orig_numb> <!-- int 4 (number)-->
<equipment_code>...</equipment_code><!-- varchar 16 (class)-->
<stop_over_code>...</stop_over_code><!-- varchar 1 (stop-over indicator)-->
<from>
<date>...</date> <!-- varchar 50 (time of departure)-->
<code>...</code> <!-- varchar 5 (departure airport code)-->
<name>...</name> <!-- varchar 64 (departure airport name)-->
<terminal>...</terminal><!-- varchar 5 (departure terminal)-->
<country>...</country> <!-- varchar 64 (departure country)-->
<state>...</state> <!-- varchar 64 (state of departure)-->
<city>...</city> <!-- varchar 64 (departure city)-->
</from>
<to>
<date>...</date> <!-- varchar 50 (arrival time)-->
<code>...</code> <!-- varchar 5 (arrival airport code)-->
<name>...</name> <!-- varchar 64 (arrival airport name)-->
<terminal>...</terminal><!-- varchar 5 (arrival terminal)-->
<country>...</country> <!-- varchar 64 (arrival country)-->
<state>...</state> <!-- varchar 64 (state of arrival)-->
<city>...</city> <!-- varchar 64 (arrival city)-->
</to>
</segment>
<segment> <!-- route -->
...
</segment>
...
<traveler> <!-- passenger -->
<orig_numb>...</orig_numb> <!-- int 4 (number)-->
<first_name>...</first_name> <!-- varchar 32 -->
<last_name>...</last_name> <!-- varchar 32 -->
<passenger_name>...</passenger_name> <!-- varchar 64 -->
<rbd>...</rbd> <!-- varchar 5 (booking class)-->
<status>...</status> <!-- varchar 32 (status)-->
<ticket_number>...</ticket_number> <!-- varchar 14 (passenger ticket number)-->
</traveler>
<traveler> <!-- пассажир -->
...
</traveler>
...
<child>
<orig_numb>...</orig_numb> <!-- int 4 -->
<first_name>...</first_name> <!-- varchar 32 -->
<last_name>...</last_name> <!-- varchar 32 -->
</child>
<child>
...
</child>
...
</ad_pnr>
3 XML format for additional booking data:
<data>
<email>...</email> <!-- varchar 128 (customer email) -->
<from>
<date>...</date> <!-- varchar 14, format YYYYMMdd HH:mm (date of check-in ) -->
</from>
<to>
<date>...</date> <!--varchar 14, format YYYYMMdd HH:mm (date of check-out) -->
</to>
<traveler> <!--traveler-->
<orig_numb>...</orig_numb> <!-- int 4 (number of the guests) -->
<first_name>...</first_name> <!-- varchar 32 (first name of the guest) -->
<last_name>...</last_name> <!-- varchar 32 (last name of the guest) -->
<traveler_name>...</traveler_name> <!-- varchar 64 (Full name of the guest) -->
</traveler>
<traveler>...</traveler> <!--next guest-->
...
</data>
Customer data (clientAttributes)
Customer data
Field | Description | Type |
Cookie | Unique identity of the payment service user in an external system, which matches the specified domainId. | String (16 chars) |
SystemLanguage | Language code of customer operational system | String (5 chars) |
BrowserLanguage | Language code of the browser | String (5 chars) |
UserLanguage | Customer language code | String (5 chars) |
TimeZone | Customer time zone GMT offset in minutes. For example: Offset GMT+2 (in hours) is equal to + 120 (in minutes) | Decimal (5) |
ConnectionType | HTTP connection type | String (16 chars) |
JsVer | Java script interpretator version | String (16 chars) |
LocalTime | Customer local time | String (128 chars) |
ScreenRes | Customer screen resolution | String (16 chars) |
ScreenPixelDepth | Color depth of customer screen | Decimal (15) |
BrowserName | Customer browser name | String (255 chars) |
CookiesEnabled | Cookie support enabled indicator | Logical (true, false) |
JavaEnabled | Java script support enabled indicator. | Logical (true, false) |
BrowserStylesheetsEnabled | css styles support. | Logical (true, false) |
BrowserPlatform | Browser platform name | String (64 chars) |
Processor | Processor name of customer computer. | String (16 chars) |
Latitude | Geographic latitude coordinates defining the position of the payer on the Earth's surface. Specified in degrees. For example: 55.755831 | Decimal (3,7) |
Longitude | Geographic longitude coordinates defining the position of the payer to the Earth's surface. Specified in degrees. For example: 37.617673 | Decimal (3,7) |
Device | Description of the user device, which is used for payment. | String (50 chars) |
DeviceUniqueID | Unique number of the user device (UDID, IMEI, MEID, ESN or IMSI). | String (50 chars) |
Application | Name of the application which is used for payment | String (50 chars) |
ApplicationVersion | Version of the application which is used for payment | String (25 chars) |
MacAddress | MAC address of the user device | String (17 chars) |
AndroidID | ID of Android device | String (20 chars) |
AccountLifetimeDays | Period of account existence in days | Decimal (5) |
OrdersNumber | Number of orders (since account creation). | Decimal (7) |
LastBuyDays | Number of days since the last purchase | Decimal (5) |
LastChangePwdDate | Date and time of last change of the user password | Data |
IsFirstBuy | Flag of customer's first purchase | Logical (true, false) |
TotalOrdersAmount | Total amount of purchases | Decimal (15,2) |
CurrentSessionTime | Time of client's session. Time (in minutes) elapsed since the login until the order creation. | Decimal (5) |
Fields, which are highlighted in the table as bold are desirable for quality of math methods work.
HTTP headers (httpAttributes)
HTTP headers
Field | Description | Type |
AcceptLanguage | Header Accept Language http- from http-request. | String (128 chars) |
UserAgent | Header User Agent http- from http-request. | String (255 chars) |
Accept | Header Accept http- from http-request. | String (255 chars) |
Referer | Header Referer http- from http-request. | String (255 chars) |
Forwarded | Header Forwarded http- from http-request. | String (16 chars) |
XForwardedFor | Header XForwarded-For http- from http-request. | String (16 chars) |
Via | Header Via http- from http-request. | String (128 chars) |
Server environment variables (serverAttributes)
Server environment variables
Field | Description | Type |
RemoteAddress | Customer IP-address | String (16 chars) |
ServerProtocol | Environment variable Server_Protocol. | String (16 chars) |
HostName | Customer host name. | String (70 chars) |
If a fields length exceeded the procedure call will fail (result code is different from zero). HTTP headers – are exception, they will be truncated to specified length and procedure call will continue.
Output parameters
Procedure call result is always the object of getAFSResult type. It contains the data of the payment check results in case of call success (result code is zero) or no data in case of call failure (result code is different from zero).
check procedure output parameters
Parameter | Description | Type |
FraudStatus | Decimal (15) | |
ReasonDescription | Description of fraud-status setting reason. | String (100 chars) |
ReasonId | Fraud-status setting reason code. | Decimal (15) |
RetCode | Execution result code. | Integer (10) |
Description | Comment to the call execution. | String (2000 chars) |
Result codes of check procedure call
Code | Description |
0 | Call is succeed, no errors. |
2 | External system authorization error. |
3 | Incorrect merchant ID is provided. |
6 | Incorrect payment type is provided. |
7 | Incorrect application/service ID is provided or this application/service ID is not belong to the external system. |
8 | Execution timeout exceeded. Execution will be continued but call request will be interrupted and this code is returned. |
1 | Other execution error. |
Synchronous check of several payments
Synchronous check of several payments procedure name is checkArray.
Input parameters
Input parameters of checkArray
| Parameter | Description | Type |
CheckPaymentParams | An array of data structures, each element of which is the structure CheckPaymentParams. | Array of data structure |
waitResults | The parameter specifies whether to wait for the end of the verification of all payments (value true) or the method returns an empty response immediately after the creation of all tasks for payment processing (value false). Transmitted payments data is processed in parallel streams, which reduces the overall processing time. | Boolean (true, false) |
Output parameters
Procedure call result is always the array of getAFSResult type objects. The result contains the data of the payment check results (result codes RetCode) in case of waiting for the end of the verification of all payments. The result contains no data (result codes RetCode are zero) without waiting for the end of the verification of all payments. More details.
Procedure for 3DS transactions data transmission
Procedure name of 3DS transactions data transmission is - set3DSecData. This procedure should be called after call (or calls) of checkPayment procedure for the payment.
Input parameters
All parameters of this procedure are mandatory.
Input parameters of set3DSecData
Parameter | Description | Type |
outPaymentId | ID of payment operation. | Decimal (15) |
outSystemId | External system ID. | Decimal (15) |
authResult | 3DSecure authorization result (Y - success, N - fail, A - attempt, U –unknown) | String (1 char) |
authRequired | Result of card 3dS involvement check (1 – involved, 0 – not involved, -1 – not-known, null – all rest) | Decimal (1) |
Output parameters
The result of the procedure call is the current fraud status of payment which can be used to make a decision on payment.
Output parameters of set3DSecData
Parameter | Description | Type |
FraudStatus | Decimal (15) | |
ReasonDescription | Description of fraud-status setting reason. | String (100 chars) |
ReasonId | Fraud-status setting reason code. | Decimal (15) |
RetCode | Execution result code. | Integer (10) |
Description | Comment to the call execution. | String (2000 chars) |
Result codes of set3DSecData procedure call
Code | Description |
0 | Call is succeed, no errors. |
2 | External system authorization error. |
4 | Non-existing payment number is provided. |
1 | Other execution error. |
Procedure of fraud-status receiving
Procedure name of fraud-status receiving is - getFraudStatus. This procedure should be called after call (or calls) of checkPayment procedure for the payment.
Input parameters
All parameters of this procedure are mandatory.
Input parameters of getFraudStatus
Parameter | Description | Type |
outPaymentId | ID of payment operation. | Decimal (15) |
outSystemId | External system ID. | Decimal (15) |
Output parameters
Procedure call result is always the object of getAFSResult type. It contains the data of the payment check results in case of call success (result code is zero) or no data in case of call failure (result code is different from zero).
Output parameters of getFraudStatus
Parameter | Description | Type |
FraudStatus | Decimal (15) | |
ReasonDescription | Description of fraud-status setting reason. | String (100 chars) |
ReasonId | Fraud-status setting reason code. | Decimal (15) |
RetCode | Execution result code. | Integer (10) |
Description | Comment to the call execution. | String (2000 chars) |
PaymentParameters | List of payment parameters | List of structures:: name — parameter name (string);; booleanValue — filled when value has logical type (true, false); doubleValue — filled when value has decimal type; stringValue — filled when value has string type; intValue — filled when value has integer type; dateValue — filled when value has data type. |
List of payment parameters PaymentParameters
Parameter | Description | Type |
date | Payment date. | Date |
calculateAmount | Payment amount in SOFI main currency. | Decimal |
outAmount | Payment amount in original currency. | Decimal (15,2) |
outCurrencyCode | Currency code (ISO 42 17). | String (3 chars) |
Customer Email. | String | |
phone | Customer phone number. | String |
mobilePhone | Customer mobile phone number. | String |
cardNumberMask | Bank card number (first 6 and last 4 digits only). | String |
cardType | Bank card type (determined by card number). | String |
cardSubType | Bank card sub-type (determined by card number). | String |
cardholder | Card-holder name. | String |
cardBankCountry | Issuer-bank country (determined by card number). | String |
cardBank | Issuer-bank name (determined by card number). | String |
expiredate | Card expiration date. | Date |
acquirer | Acquirer name (unique within the external system). | String |
cookie | Unique payer identity from external system. | String |
ip | Customer IP-address. | String |
ipCountry | Customer country (determined by customer IP-address). | String |
billNumber | Bill number from external system. | String |
orderNumber | Order number for payment operation. | String |
outStatus | Payment operation status. | Decimal |
outStatusName | Operation status name. | String |
fraudStatus | Decimal | |
reasonId | Fraud-status setting reason code. | Decimal |
testMode | Test mode. | Logical |
usedCSC | Card Secure Code was used indicator. | Logical |
3DSecAuthresult | 3DSecure authorization result (Y - success, N - fail, a - Attempt, U –unknown). | String |
3DSecAuthrequired | Result of card 3dS involvement check (1 – involved, 0 – not involved, -1 – not-known, null – all rest). | Decimal |
recurringIndicator | Recurring payment indicator. | Logical |
billingPostalCode | BillingData. Customer postal index. | String |
billingAddress | BillingData. Customer postal address. | String |
billingFirstName | BillingData. Customer name. | String |
billingLastName | BillingData. Customer second name. | String |
billingPhoneNumber | BillingData. Customer phone number. | String |
billingEMailAddress | BillingData. Customer E-mail. | String |
customer | Customer full name. | String |
customerCountry | Country (as customer said). | String |
customerRegion | Region (as customer said). | String |
customerCity | City (as customer said). | String |
customerAddress | Address (as customer said).. | String |
clientSystemLanguage | Language code of customer operational system. | String |
clientLocalTime | Customer local time. | String |
clientUserLanguage | Customer language code. | String |
clientBrowserLanguage | Language code of customer's browser. | String |
clientBrowserPlatform | Browser platform name. | String |
clientJsBrowserName | Customer browser name. | String |
clientJsVersion | Java script interpretator version. | String |
clientTimeZone | Customer time zone GMT offset in minutes. For example, offset GMT+2 (in hours) is equal to + 120 (in minutes). | String |
clientCookieEnabled | Cookie support enabled indicator. | Logical |
clientJavaEnabled | Java script support enabled indicator. | Logical |
clientConnectionType | HTTP connection type. | String |
clientProcessor | Processor name of customer computer. | String |
clientScreenRes | Customer screen resolution. | String |
clientScreenPixelDepth | Color depth of customer screen. | Decimal |
clientStylesheetsEnabled | css styles support. | Logical |
httpAccept | Header Accept of HTTP-request. | String |
httpAcceptLanguage | Header Accept Language of HTTP-request. | String |
httpReferer | Header Referer of HTTP-request. | String |
httpServerProtocol | Environment variable Server_Protocol. | String |
httpUserAgent | Header User Agent of HTTP-request. | String |
hostname | Customer computer host name. | String |
Result codes of getFraudStatus procedure call
Code | Description |
0 | Call is succeed. No errors. |
2 | External system authorization error. |
4 | Non-existing payment number is provided. |
1 | Other execution error. |
Procedure for payment status change
Procedure for payment status change is setStatus.
Input parameters
The only input parameter that is transmitted from external system for payment status change is parameter params, which is a data structure called SetPaymentStatusParams.
Fields of SetPaymentStatusParams
Field | Description | Type |
outPaymentId | Payment operation ID within the external system. | Decimal (15) |
outSystemId | External system ID. | Decimal (15)) |
outStatus | Decimal (15) | |
timeOut | Execution time-out in milliseconds. If value is not provided then default value (10 s.) is used. If provided value less or equal to zero then there is no time-out in the execution. | Decimal (15), optional |
approvalCode | Operation execution code (from processing center). Each processing center uses its own codes. | String (12) |
psDate | Date of a payment transaction execution in processing center. UTC data (GMT-0) or GMT+ hour-offset. | DateTime |
responseCode | The result code of payment from processing center. | String (70) |
responseComment | Explanation of the result code from the payment processing center. | String (128) |
externalTransactionID | · Retrieval Reference Number (formed by processing center by its own algorithm) for processing centers which transmitting RRN (currently: BPC, BPCBel, RAIF, SviazBank, MBank, AmexPOA and MULT-family) or · another possible transaction number. | String (50) |
meanNumber | The E-wallet ID is transmitted when it was not available for transmission in the procedure call Check. | String (70) |
meanTypeGroup | Group of payment means: 1 - card (by default), 2 – E-wallet | Integer (1) |
meanType | Type of E-wallet (required for E-wallets). Available types of electronic wallets are presented in the table «Type of E-wallets». | String (3 chars) |
reasonId | The reason for setting the operation status. | Integer (15) |
reasonComment | Comment on the reason for setting the status. | String (400 chars) |
Fields, which are highlighted by bold – are mandatory.
Reasons of status setting are relevant for those operations which ended unsuccessfully before the authorization.
Reasons of operation status setting
Name of reason | Code | Description |
Data input timeout | 1 | The user has not finished the input of personal data, the choice of payment means, the entry of payment means data in the allotted time for payment. |
Refusal of payment | 2 | The payer is clearly pressed the cancel button during the process of payment and refused to continue paying. |
Exceeded the limits | 3 | One of the established limits of merchant does not allow the payment. |
Blocked by blacklist | 4 | The payer IP blacklist or blacklist of payment means does not allow the payment. |
Blocked by filter | 5 | One of the active white or others blacklists of merchant does not allow the payment or card does not participate in the promotion. |
3DS timeout | 6 | Payer has not completed the 3DS authentication (on the ACS side) in the allotted time on it. |
3DS result N | 7 | The payer failed to pass the 3DS authentication. |
3DS result U | 8 | The error occurred during the 3DS authentication. |
Configuration error | 9 | Errors associated with the inability to make the payment due to settings of merchant or system (there is no suitable processing, we cannot carry out such currency, OneClick mistakes, and so on). |
Technical error | 10 | An error occurred on the side of the external system (general, system and other technical mistakes during the preparation for the payment). |
Output parameters
Procedure call result is always the replay which contains the execution result code and result description in case of call success (RetCode is zero) or no data in case of call failure (result code is different from zero).
setStatus output parameters
Parameter | Description | Type |
RetCode | Execution result code. | Integer (10) |
Description | Execution result comment. | String (2000 chars) |
Result codes of setStatus procedure
Code | Description |
0 | Call is succeed. No errors. |
2 | External system authorization error. |
4 | Non-existing payment number is provided. |
5 | Incorrect operation code is provided. |
8 | Execution timeout exceeded. Execution will be continued but call request will be interrupted and this code is returned. |
1 | Other execution error. |
Merchant data update procedure
Procedure setMerchantData can be used to set and change the merchant data.
Input parameters
All procedure parameters (except Email) are mandatory.
setMerchantData input parameters
Parameter | Description | Type |
outSystemId | External system ID. | Decimal (15) |
outMerchantId | Merchant ID in the external system. | Decimal (15) |
merchantName | Merchant name. | String (128 chars) |
merchantEmail | E-mail of merchant. | String (64 chars), optional |
isOnMonitoring | Should be monitored. | Logical (true, false) |
categoryId | Merchant category ID (see merchant categories below). | Decimal (15) |
mcc | Merchant Category Code | String (4 digits) |
When merchant exists then his data is updated during execution of this procedure. When there is no merchant with such ID then a new one is created and the merchant data stored in SOFI.
Merchant categories
Code | Name |
19 | Books, Video, CD/DVD |
20 | Tickets for theater, cinema, concerts |
21 | Gambling industry |
22 | Flowers, presents, parfume |
23 | Art, collectible models, honors |
24 | Dating services |
25 | SoftWare |
26 | Internet hosting, solutions, cable-TV |
27 | Education / conferences / forums |
28 | Household appliances and electronics |
29 | Information and advisory services |
30 | Computers and accessories |
31 | Foodstuffs |
32 | Media |
34 | Miscellanea |
35 | Car-parts |
36 | Booking of air and rail tickets, hotels, tours, cars |
37 | Libraries |
38 | Beauty and Health |
39 | Clothing and footwear |
40 | Household Goods / Furniture |
41 | Tobacco |
43 | Translation services |
44 | Charity |
46 | Photo & Graphic |
47 | Communication and Telecommunication |
48 | Security systems |
49 | On-line games |
50 | Downloads (Music, films, TV programs, books) |
51 | Sport and Tourism |
52 | Jewelry and Watches |
53 | Auctions |
54 | Utilities and other payments |
55 | Advertisement |
56 | Insurance |
57 | Air-companies |
58 | Hotels |
59 | Coupons / Certificates |
77 | Aggregators |
78 | Goods for children |
97 | On-line trading |
98 | Employment / recruitment / freelance |
Output parameters
Procedure call result is always the replay which contains the execution result code and result description in case of call success (RetCode is zero) or no data in case of call failure (result code is different from zero).
setMerchantData output parameters
Parameter | Description | Type |
RetCode | Execution result code. | Integer (10) |
Description | Execution result comment. | String (2000 chars) |
Result codes of setPaymentStatus
Code | Description |
0 | Call is succeed. No errors. |
2 | External system authorization error. |
1 | Other execution error. |