You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 50 Next »

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:

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:

  1. 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.
  2. 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 (see more sect.5.4.1)

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 number* 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)

Email

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)

Fax

Fax 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)**

Text

BookingData

XML with additional booking data***

Text

3DSecAuthrequired

Result of card 3dS involvement check (1 – involved, 0 – not involved, -1 – not-known, null – all rest)

Decimal (1)

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

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