www.assist.ru

Versions Compared

Old Version 107

changes.mady.by.user Oksana Chizhikova

Saved on

compared with

New Version Current

changes.mady.by.user Oksana Chizhikova

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Parameters outSystemId and outPaymentId should be assigned to the corresponding ID values (see table "Mandatory fields of CheckPaymentParams").

Anchor
41
41


Payment check procedure

Payment check procedure name is check.

...

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

...

Field

Description

Type

Meannumber

The encrypted card number* 1 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)**2

Text

BookingData

XML with additional booking data***3

Text

3DSecAuthrequired

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

Decimal (1)

Anchor
1
1


1*To get access to the service for receiving irreversible token from ASSIST company, you have to contact technical support team (support@assist.ru).

...

E-wallet type

E-wallet name

WM

WebMoney

EP

EasyPay

QW

QIWI

QB

QIWIBeeline

QM

QIWIMts

QF

QIWIMegafon

MB

Mobicon

YM

YandexMoney

Anchor
2
2


2 ** XML format for additional flight-data:

Code Block
languagexml
<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>

Anchor
3
3


3 *** XML format for additional booking data:

...

Code

Description

0

Call is succeed, no errors.

2

External system authorization error.

4

Non-existing payment number is provided.

1

Other execution error.

Anchor
44
44


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

Fraud-status code.

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)

email

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

Fraud-status code.

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

Payment operation status.

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.

Back on top