Card system protocol

Requests are sent to the card authorization server via TCP/IP.

The card authorization server connects to the card system application server, so a forced closing of the application server is not allowed, and if required, the card authorization server should be restarted.

The request should be sent in proper format (with due regard to uppercase and lowercase characters).

For CRM 5 based on TCP/IP, all requests are accompanied by a header looking as follows:

Message-ID: 1
Message-Type: Request
Time: 2010-01-26 13:57:23
Terminal-Type: 1 Content-Length: 123,

where:

"Message-ID" is the message identifier.
"Message-Type" is the message type (Request).
"Time" stands for the time, when the message was sent, formatted as YYYY-MM-DD HH:NN:SS.
"Terminal-Type" is the type of the terminal, the alphanumeric code of which is maintained in the card system under the menu "Software classifiers" and is configured during the terminal installation. "Content-Length" is the length of the data package, in bytes (from "<?xml" to "</Message>").

A sample request to the card authorization server (an empty line between the header and the XML package is mandatory):

Message-ID: 1
Message-Type: Request
Time: 2010-01-26 13:57:23
Terminal-Type: 123
Content-Length: 210

<?xml version="1.0" encoding="Windows-1251" standalone="yes" ?>
<Message Action="Get card info" Terminal_Type="123" Global_Type="ABC" Unit_ID="1" User_ID="1">
<Card_Code>123456789</Card_Code>
<Include>Holder</Include>
</Message>
CODE

"Global_Type" is provided at the time of the key receipt; should be specified for each request.
"Unit_ID" — reserved.
"User_ID" — reserved.

Sample response:
200 OK

Message-Type: Response
Message-ID: 1
Time: 2010-01-27 17:33:36
Content-Length: 736

<?xml version="1.0" encoding="Windows-1251" standalone="yes" ?>
<Cards>
 <Card>
  <Status>Active</Status>
  <Offered>2008-10-23</Offered>
  <Expired>2009-10-23</Expired>
  <Group_ID>1</Group_ID>
  <Group_Name>Main group</Group_Name>
  
  <Holders>
   <Holder>
    <Division_ID>1</Division_ID>
    <Holder_ID>117</Holder_ID>
    <L_Name>IVANOV</L_Name>
    <F_Name>IVAN</F_Name>
    <M_Name>IVANOVICH</M_Name>
    <Full_Name>IVANOV IVAN IVANOVICH</Full_Name>
    <Birth>1987-01-04</Birth>
    <Gender>Male</Gender>
    <Marrital>No</Marrital>
    <Language_ID>1049</Language_ID>
    <Language_Name>Russian</Language_Name>
   </Holder>
  </Holders>
  
 </Card>
</Cards>
CODE

For CRM 7 based on HTTP, requests are sent without the header described above (XML format into UTF-8).

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<Message  Message_ID="63" Action="Get card info" Terminal_Type="123" Unit_ID="1" User_ID="1" Sys_Date_Time="2016-04-20 12:57:48.38 +03:00">
<Card_Code>123456789</Card_Code>
<Include>Holder</Include>
</Message>
CODE

"Global_Type" is not required for CRM 7.
"Unit_ID" — reserved.
"User_ID" — reserved.

Sample response:

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Cards Message_ID="63">
 <Card>
  <Status>Active</Status>
  <Offered>2008-10-23</Offered>
  <Expired>2009-10-23</Expired>
  <Group_ID>1</Group_ID>
  <Group_Name>Main group</Group_Name>
  
  <Holders>
   <Holder>
    <Division_ID>1</Division_ID>
    <Holder_ID>117</Holder_ID>
    <L_Name>IVANOV</L_Name>
    <F_Name>IVAN</F_Name>
    <M_Name>IVANOVICH</M_Name>
    <Full_Name>IVANOV IVAN IVANOVICH</Full_Name>
    <Birth>1987-01-04</Birth>
    <Gender>Male</Gender>
    <Marrital>No</Marrital>
    <Language_ID>1049</Language_ID>
    <Language_Name>Russian</Language_Name>
   </Holder>
  </Holders>
  
 </Card>
</Cards>
CODE
  1. 0 System

0.1. Server version request ("Get version")

Request to the card authorization server:

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Get version" Terminal_Type="123" Global_Type="ABC" Unit_ID="1" User_ID="1"> </Message>
CODE

XML response format:

  Version
 Server_Info (version)
  Major (version number)
  Minor (subversion number)
  Release (release number)
  Build (build number)

0.2. Database server time request ("Get system time")

Request to the card authorization server:

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Get system time" Terminal_Type="123" Global_Type="ABC" Unit_ID="1" 
User_ID="1"> </Message>
CODE

XML response format:

 SystemTime
Date (date)
Time (time)
DateTime (date and time)

  1. Cards

1.1. Card information request ("Get card info")

In the "Include" section of the XML request, the required information parameters should be specified.

"Holder_NoCount" — if this parameter is specified, the XML response will not contain tags for the number of cards, accounts, etc. This helps reduce the database load and increase the response speed.

"Account_Available" — restricts the account output. When specified, the following accounts are ignored at the time of response generation:

  • blocked;
  • with a simultaneous prohibition on debiting and crediting.

"Holder_Coupon_Available" — restricts the coupon output. When specified, the following coupons are ignored:

  • deleted;
  • inactive;
  • redeemed;
  • pending (coupon lifetime);
  • expired (coupon lifetime);
  • unavailable for redemption by the requested classifier;
  • restricted by the timing scheme.

"Coupon_Index" — the initial index in the requested coupon list (by default, 1).
"Coupon_Count" — the number of coupons in the requested coupon list (by default, 999999).

In the XML response, the debit (Account_Debit_Enabled) and credit (Account_Credit_Enabled) enable flags are generated based on the following data:

  • account type activity;
  • entitlement of the requested classifier to use the given account type:
  • availability of an active link;
  • link usage schedule.

Depending on the CRM offers configuration, the "Account" sections of the XML response may contain the following tags:
Extension_ID (additional rate scheme code, with reference to offers)
Extension_Name (rate scheme name)
Extension_Rate (additional rate, with reference to offers)
Extension_DiscountLimit (a limit on the discount provided)
Extension_BalanceLimit (a limit on the use of the balance)
Extension_CreditUseLimit (a limit on the number of card credit operations)
Extension_DebitUseLimit (a limit on the number of card debit operations)
Extension_AllUseLimit (a limit on the number of card operations)
Extension_CountCurrentLevel (the number of visits over a period)
Extension_CountNextLevel (the number of visits till the next level)
Extension_AmountCurrentLevel (the amount of earned points over a period)
Extension_AmountNextLevel (the amount of points till the net level)


Request to the card authorization server:

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Get card info" Terminal_Type="123" Global_Type="ABC" Unit_ID="1" 
User_ID="1">
<Is_Virtual_Card>Yes</Is_Virtual_Card>
<Card_Code>123456789</Card_Code>
<Include>Account, Account_Available, Holder, Holder_Image, Holder_Contact, Holder_Address, Holder_Relative, Holder_Contract, Holder_Card, Holder_Coupon, 
Holder_Coupon_Available, Holder_Attribute, Card_Property, Holder_Property</Include>
<Image_Format Original="Yes" Width="200" Height="150" 
Compression="75">JPEG</Image_Format>
<Account_Filter>
<Account_Class>2</Account_Class>
<Account_Type_ID>1</Account_Type_ID>
</Account_Filter>
<Coupon_Index>1</Coupon_Index>
<Coupon_Count>10</Coupon_Count>
</Message>
CODE

XML response format:

  Cards

  Card (card information)
Card_Code (card number)
Is_Virtual_Card (check for a virtual card)
"Yes"
"No"
Status (card status)
"Active"
"Inactive"
"Deleted"
"Disabled"
"Blocked"
"Issue" — physical issue
Block_Reason (the reason for blocking)
Carrier_Data (magnetic tape information)
Offered (date of maintenance)
Expired (date of expiry)
Group_ID (group code)
Group_Name (group name)
Holder_ID (holder code)
Owner_ID (owner code)

  Accounts (the list of accounts, Include = Account)
Account (account)
Status (account status)
"Active"
"Blocked"
Block_Reason (the reason for blocking, if applicable)
Account_Number (account number)
Account_Class (account class)

  "1" — bonus account

  "2" — discount account

  "3" — debit account

  "4" — credit account

  "5" — funds spent

  "6" — membership

  "99" — user account

Account_Type_ID (account type code)

Account_Type_Name (account type name)

Account_Debit_Enabled (the possibility of debiting the account)

  "Yes" — debit enabled

  "No" — debit disabled

Account_Debit_Priority (account priority for debiting)

Account_Debit_K (debit ratio for the classifier)
Account_Credit_Enabled (the possibility of crediting the account)

  "Yes" — credit enabled

  "No" — credit disabled

Account_Credit_Priority (account priority for crediting)

Account_Credit_K (credit ratio for the classifier)

Account_Level_ID (account level code)

Account_Level_Name (account level name)

Transaction_Debit_ID (debit transaction type)

Transaction_Credit_ID (credit transaction type)

Scheme_ID (rate scheme internal code)

External_ID (rate scheme external code)
Scheme_Name (rate scheme name)

Base_Rate (basic interest rate)

Create (account creation date)

Credit_Depth (credit limit)

Balance (balance, with reference to the debit ration for the classifier)
Auto_Change_Levels (automatic transition between levels)

  "No" — unavailable

  "Yes" — available

Time_ID (timing scheme code)

Time_Name (timing scheme name)

Current_Rate (current interest rate, with reference to the timing scheme)

Account_Code (rate scheme internal code, with reference to the timing scheme)
Account_Code_Ext (rate scheme external code, with reference to the timing scheme)

   

  Holders (the list of holders, Include = Holder)

  Holder

  Deleted (deletion flag)

  "Yes" — deleted

  "No" — not deleted

Division_ID (division code)

Division_Name (division name)

Group_ID (group code)

Group_Name (group name)

Holder_ID (holder code)

INN (holder TIN)

External_Code (external code)

Unpay_Type_ID (non-payer code)

Unpay_Type_Name (non-payer name)

L_Name (last name)

F_Name (first name)

M_Name (middle/patronymic name)

Full_Name (full name)
Birth (date of birth)

  "Unknown" — not specified

Gender (gender)

  "Unknown" — not specified

  "Male"

  "Female"

Marital (marital status)

  "Unknown" — not specified

  "No" — single/unmarried

  "Yes" — married

Smoke (smoking)

  "No" — non-smoker

  "Yes" — smoker

Verification (verification)

  "No" — not verified

  "Yes" — verified

Image (availability of a photo; the Hash attribute contains the image hash used to determine the update status: "select HASHBYTES('MD5', cast(PHOTO as nvarchar(4000))) from CARD_PEOPLES"

  )

  "No" — not available

  "Yes" — available
Language_ID (language code)

  "Unknown" — not specified

Language_Name (language name)

  "Unknown" — not specified
Remarks (comments)

   

Holders_Relatives (the list of relatives, Include = Holder_Relative)

  Holder_Relative

Holder_ID (holder code)

Holder (relative information)

Division_ID (division code)

Holder_ID (holder code)

L_Name (last name)

F_Name (first name)

M_Name (middle/patronymic name)

Full_Name (full name)
Birth (date of birth)

  "Unknown" — not specified

   

Holders_Contracts (the list of holder contracts, Include = Holder_Contract)

Holder_Contract

Holder_ID (holder code)

Contract (contract information)

Contract_ID (contract code)
Name (contract name)

Type_ID (contract type)

Type_Name (contract type name)

Offered (valid-from date)

Expired (valid-to date)

Holders (the list of participants)

  Holder

Division_ID (division code)

Holder_ID (holder code)

L_Name (last name)

F_Name (first name)

M_Name (middle/patronymic)

Full_Name (full name)
Birth (date of birth)

  "Unknown" — not specified


  Holders_Images (the list of holder photos, Include = Holder_Image)

  Holder_Image

  Holder_ID (holder code)

  Photo (a Base64 image)

  Format (data format)

"BMP" — Windows Bitmap (default)

 "JPEG" — Joint Photographic Experts Group


  Holders_Contacts (the list of holder contacts, Include = Holder_Contact)

  Holder_Contact

  Holder_ID (holder code)

  Contact (contact information)

  Is_Virtual_Card (check for a virtual card)

  "Yes"

  "No"

  Deleted (deletion flag)

  "Yes" — deleted

  "No" — not deleted

  Dispatch (permit for dispatch)

  "Yes" — allowed

  "No" — not allowed

  Contact_ID (contact code)

  Type_ID (type)

  Type_Code (external type code)

  Type_Name (type name)

  Value (value)
  Notes (notes)


  Holders_Addresses (the list of holder addresses, Include = Holder_Address)

  Holder_Address

  Holder_ID (holder code)

  Address (contact information)

  Deleted (deletion flag)

  "Yes" — deleted

  "No" — not deleted

  Address_ID (address identifier)

  Type_ID (type)

  Type_Name (name)

  Country_ID (country identifier)

  Country (country)

  ZIP (postal code)

  Region (region)

  City_ID (city identifier)

  City (city)

  Street_ID (street identifier)

  Street (street)

  Metro_Station_ID (metro station identifier)

  Metro_Station (metro station)
  House (house)

  Building (building)

  Entry (entrance)

  Floor (floor)

  Apartments (apartment)

  Entry_Code (entry phone code)
  DopInfo (additional information)


Holders_Cards (the list of holder cards, Include = Holder_Card)

  Holder_Card

  Holder_ID (holder code)

  Card (card information)

  Card_Code (card number)

  Is_Virtual_Card (check for a virtual card)

  "Yes"

  "No"

  Is_Confirm_Manager (manager confirmation required)

  "Yes"

  "No"

  Status (card status)

  "Active"

  "Inactive"

  "Deleted"

  "Blocked"

  "Disabled"

  "Issue" — physical issue

  Block_Reason (the reason for blocking)

  Carrier_Data (magnetic tape information)

  Offered (date of maintenance)

  Expired (date of expiry)

  Group_ID (group code)

  Group_Name (group name)

  Holder_ID (holder code)

  Owner_ID (owner code)



  Cards_Properties (the list of card properties, Include = Card_Property)

  Card_Property

  Property_ID (property code)

  Property_Name (property name)

  Property_Code (external property code)

  Value_ID (value code)

  Value_Name (value name)

  Value_Value (external value)

  Value_Type (value type)

  "None" — not specified

  "Integer" — an integer number: 1234

  "Float" — a real number: 12.34

  "String" — a string

  "Date" — a date: 2014-12-31

  "Time" — time: 12:34:56

  "DateTime" — date and time: 2014-12-31T12:34:56

  Holders_Properties (the list of holder properties, Include = Holder_Property)

  Holder_Property
the structure is similar to Cards_Properties
Holders_Coupons (the list of holder coupons, Include = Holder_Coupon)
in case of Holder_Coupon_Available, only those coupons will be returned, which are available for sale in the context of the given classifier

  Holder_Coupon

  Holder_ID (holder code)

  Coupon (coupon information)
Coupon_ID (coupon code)

  Coupon_Code (coupon number)

  Coupon_Type_ID (coupon type)

  Holder_ID (holder code)

  Status (coupon status)

  Mode (usage attribute)

  NoLimit (reusable)

  "Active"

  "Inactive"

  "Deleted"

  "Disabled"

  "Failed time" — active, with usage limited based on the timing scheme

  Offered (valid-from date)

  Expired (valid-to date)

  Discounts (discount data — for a discount coupon)

  Discount

  Discount_ID (rate scheme internal code)

  Discount_Name (rate scheme name)

  Discount_Rate (rate)

  Discount_Limit (discount limit)

  External_ID (rate scheme external code)

  Amounts (amount data — for an amount coupon)

  Amount

  Amount_Base (basic coupon amount)

  Amount (payment amount)

  Coupon_Type_Details (the list of goods — for a product coupon)

  Coupon_Type_Detail (the list of groups)

  Coupon_Type_Detail_Name (group name)

  Coupon_Type_Detail_Notes (comments)

  Coupon_Type_Detail_Max (total quota of goods within the group)

  Coupon_Type_Detail_Priority (priority)

  Coupon_Type_Detail (the list of goods)

  Coupon_Type_Detail_External_Code (goods code)
  Coupon_Type_Detail_Name (goods name)

  Coupon_Type_Detail_Notes (comments)

  Coupon_Type_Detail_Max (goods quota)

  Coupon_Type_Detail_Kind (value type)

  "summ" — sum total

  "percent" — percentage

  "price" — price

  Coupon_Type_Detail_Value (value)

  Coupon_Type_Detail_Priority (priority)

     Coupon_Type_Detail_Default (default goods)

  Terminals_Types (the list of classifiers)
All (unlimited usage attribute)

  "True" — no restriction by terminal

  Terminal_Type (classifier information)

  Self (terminal ownership attribute)

  "True" — own terminal

     Terminal_Type_ID (classifier code)

Terminal_Type_Name (classifier name)

  Notes (comment)


  Holders_Attributes (the list of holder attributes, Include = Holder_Attribute)

   Holder_Attribute

  Holder_ID (holder code)

  Attribute (attribute information)
  Attribute_ID (attribute code)

  Attribute_Name (attribute name)

  Attribute_Value (attribute value)

  "Yes" — set

  "No" — reset

  Remarks (comment)
1.2. Card blocking ("Card block")

Request to the card authorization server:

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Card block" Terminal_Type="2" Global_Type="ABC" Unit_ID="1" User_ID="1">
<Card_Code>123456789</Card_Code>
<Remarks>Card blocking due to inactivity</Remarks>
</Message>
CODE

1.3. Card deactivation ("Card inactive")

Request to the card authorization server:

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Card inactive" Terminal_Type="2" Global_Type="ABC" Unit_ID="1" User_ID="1">
<Card_Code>123456789</Card_Code> </Message>
CODE

1.4. Card activation ("Card active")

"Expired" — an optional parameter

Request to the card authorization server:

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Card active" Terminal_Type="2" Global_Type="ABC" Unit_ID="1" User_ID="1">
<Card_Code>123456789</Card_Code>
<Expired>2015-12-31</Expired>
</Message>
CODE

In CRM 7, the functionality of an active card prolongation has been added.

A sample request to the card authorization server with the purpose of prolonging the card validity for 1.5 years:

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Card active" Terminal_Type="2" Global_Type="ABC" Unit_ID="1" User_ID="1">
<Card_Code>123456789</Card_Code>
<Expired>0001-06-00</Expired>
</Message>

CODE

In case of a prolongation for a period, the new validity term is defined as follows:

- card not expired yet — prolongation from the current expiry date;
- card already expired — prolongation from the current date.

A sample request to the card authorization server with the purpose of prolonging the card validity until December 31, 2020:

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Card active" Terminal_Type="2" Global_Type="ABC" Unit_ID="1" User_ID="1">
<Card_Code>123456789</Card_Code>
<Expired>2020-12-31</Expired>
</Message>
CODE

1.5. Card annulment ("Card disable")

Request to the card authorization server:

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Card disable" Terminal_Type="2" Global_Type="ABC" Unit_ID="1" User_ID="1">
<Card_Code>123456789</Card_Code>
 </Message>
CODE

1.6. Card transfer to another holder ("Card transfer")

Request to the card authorization server:

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Card transfer" Terminal_Type="2" Global_Type="ABC" Unit_ID="1" 
User_ID="1">
<Card_Code>123456789</Card_Code>
<Holder_ID>10000000000001</Holder_ID>
<Only_Free>False</Only_Free>
</Message>
CODE

"Only_Free" — only unassigned cards

  1. Accounts
    • Account blocking ("Account block")

Request to the card authorization server:

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Account block" Terminal_Type="2" Global_Type="ABC" Unit_ID="1" 
User_ID="1">
<Account_Number>02.00007.00000041.0001</Account_Number>
<Remarks>Account blocking due to missing transactions</Remarks>
</Message>
CODE

2.2. Account activation ("Account active")
Request to the card authorization server:

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Account active" Terminal_Type="2" Global_Type="ABC" Unit_ID="1" 
User_ID="1">
<Account_Number>02.00007.00000041.0001</Account_Number>
</Message>
CODE
  1. Coupons
    • Requesting the list of coupon types ("Get coupons types info")


<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Get coupons types info" Terminal_Type="2" Global_Type="ABC" Unit_ID="1" 
User_ID="1">
</Message>

CODE

XML request format:

  Coupons_Types (the list of coupon types)
Coupon_Type (coupon type information)

  Coupon_Type_ID (coupon type code)

  Coupon_Type_Name (coupon type name)

  Coupon_Type_Notes (comments on the coupon type)

  Discount_Name (rate scheme name — for a discount coupon)

  Discount_Rate (rate — for a discount coupon)

  Discount_Limit (discount amount limit — for a discount coupon)

  Summ (basic coupon amount — for an amount coupon)

  Coupon_Type_Details (the list of goods — for a product coupon)

  Coupon_Type_Detail (the list of groups)

  Coupon_Type_Detail_Name (group name)

  Coupon_Type_Detail_Notes (comments)

  Coupon_Type_Detail_Max (total quota of goods within the group)

  Coupon_Type_Detail_Priority (priority)

  Coupon_Type_Detail (the list of goods)

         Coupon_Type_Detail_External_Code (goods code)

        Coupon_Type_Detail_Name (goods name)

       Coupon_Type_Detail_Notes (comments)

       Coupon_Type_Detail_Max (goods quota)

       Coupon_Type_Detail_Kind (value type)

                 "summ" — sum total

                 "percent" — percentage

                 "price" — price

       Coupon_Type_Detail_Value (value)

       Coupon_Type_Detail_Priority (priority)

       Coupon_Type_Detail_Default (default goods)

  Terminals_Types (the list of classifiers)
All (unlimited usage attribute)

  "True" — no restriction by terminal

  Terminal_Type (classifier information)

  Self (terminal ownership attribute)

                                                              "True" — own terminal

  Terminal_Type_ID (classifier code)

  Terminal_Type_Name (classifier name)


3.2. Requesting coupon generation ("Add coupons")

There can be a situation, when a coupon is generated and assigned to its holder, but no response is received for one reason or another. In this case, a repeated request (copy) is sent with a mandatory specification of the "Message-ID" (message identifier) parameter, equivalent to the previous request, the response to which has not been received.

The "External_ID" parameter in the request reflects an external code, e.g., the receipt number.

"Coupon_Type_ID" and "Terminals_Types" parameters are mandatory. In case of an empty list (<Terminals_Types />), classifiers are taken from the list of coupon type classifiers. If the attribute "All" (<Terminals_Types All="True">) is specified, the coupon will be applicable at all points. If a list of classifiers is provided, the coupon will be valid only for classifiers belonging to this list.

"Status" — can take the "Active" value; in this case, the coupon will be activated upon issue.

"Holder_ID" is the identifier of the person that will hold the coupon (optional parameter). If not specified, the coupon will be non-personalized.

"Offered" and "Expired" — the start and end dates of coupon validity. If these parameters are not specified, a termless coupon is implied.

At the output, the coupon code (Coupon_ID) and coupon number (Coupon_Code) are received for display purposes.

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Add coupons" Terminal_Type="2" Global_Type="ABC" Unit_ID="1" User_ID="1">
<Coupon>
<Coupon_Type_ID>1</Coupon_Type_ID>
<Status>Active</Status>
<External_ID>123</External_ID>
<Holder_ID>1</Holder_ID>
<Offered>2010-01-01</Offered>
<Expired>2010-01-31</Expired>
<Notes></Notes>
<Terminals_Types>
<Terminal_Type>
<Terminal_Type_ID>123</Terminal_Type_ID>
</Terminal_Type>
</Terminals_Types>
</Coupon>
</Message>
CODE

3.3. Requesting coupon activation ("Coupon active")

The "Summ" tag is relevant for an amount coupon and is required to check the nominal value when activating the coupon at a cash desk (optional parameter).

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Coupon active" Terminal_Type="2" Global_Type="ABC" Unit_ID="1" 
User_ID="1">
<Coupon_ID>123456789012345678</Coupon_ID>
<Summ>123.45</Summ>
</Message>
CODE

3.4. Requesting coupon information ("Get coupon info")

In case of a personalized coupon ("Holder_ID" is available and filled), accounts, cards, relatives and other details can be requested in addition to the XML response given below (see the "Get card info" request).

Request to the card authorization server:

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Get coupon info" Terminal_Type="123" Global_Type="ABC" Unit_ID="1" User_ID="1">
<Coupon_ID>123456789012345678</Coupon_ID>
</Message>
CODE

XML response format:

  Coupons

  Coupon (coupon information)
Coupon_ID (coupon code)

  Coupon_Code (coupon number)

  Coupon_Type_ID (coupon type)

  Holder_ID (holder code)

  Timing_Scheme_ID (timing scheme code, if applicable to the coupon type)

  Status (coupon status)

  Mode (usage attribute)

  NoLimit (reusable)

  "Active"

  "Inactive"

  "Deleted"

  "Disabled"

  "Failed time" — active status, but with usage limited based on the timing scheme

  Offered (valid-from date)

  Expired (valid-to date)

  Coupon_Type_Details (the list of goods)
Coupon_Type_Detail (the list of groups)

  Coupon_Type_Detail_Name (group name)

  Coupon_Type_Detail_Notes (comments)

  Coupon_Type_Detail_Max (total quota of goods within the group)

  Coupon_Type_Detail_Priority (priority)

  Coupon_Type_Detail (the list of goods)

  Coupon_Type_Detail_External_Code (goods code)

  Coupon_Type_Detail_Name (goods name)

  Coupon_Type_Detail_Notes (comments)

  Coupon_Type_Detail_Max (goods quota)

  Coupon_Type_Detail_Kind (value type)

  "summ" — sum total

  "percent" — percentage

  "price" — price

  Coupon_Type_Detail_Value (value)

  Coupon_Type_Detail_Priority (priority)

  Coupon_Type_Detail_Default (default goods)

  Terminals_Types (the list of classifiers)
All (unlimited usage attribute)

  "True" — no restriction by terminal

  Terminal_Type (classifier information)

  Self (terminal ownership attribute)

  "True" — own terminal

  Terminal_Type_ID (classifier code)

  Terminal_Type_Name (classifier name)
Notes (comment)

  1. Classifiers

4.1. Requesting the list of classifiers ("Get terminals types info")

If the "Terminal_Type" list element has a Self="True" attribute, it stands for the classifier, in terms of which the request was initiated:

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Get terminals types info" Terminal_Type="2" Global_Type="ABC" Unit_ID="1" 
User_ID="1"> </Message>

CODE

XML response format:

Terminals_Types (the list of classifiers)

  Terminal_Type (classifier information)

  Terminal_Type_ID (classifier code)

  Terminal_Type_Name (classifier name)

  Terminal_Type_Type (classifier type)

  Terminal_Type_TimeBegin (classifier operation start time)

  Terminal_Type_TimeZone (classifier time zone)



 

  1. Transactions ("Transaction")

Remarks – String[255]

Dop_Info – Blob

Transaction_Time — the time (time zone required: 1999-12-12 12:30:30.12 +03:00) of transaction execution (transaction package can contain transactions with different execution time at the cash desk).

"Transaction_Life" is the lifetime (inclusive of date) of the accrued bonuses; for bonus accounts only (optional field).

"Transaction_Delay" reflects the date and time of bonus accounting at the account balance; for bonus accounts only (optional field).

Below, you can see 3 parameters, based on which an external transaction can be fully identified. This parameter is mandatory when executing transactions in case of using return operations in the system. It means that the combination of these parameters should unambiguously identify the operation being returned (in this case, "External_ID" is mandatory).

"External_ID" is an external operation identifier, e.g., the receipt number.

"External_Index" is an additional external identifier.

"External_Date" is an external operation date, e.g., the working shift date (added in CRM 6.00).

5.1. Crediting by account number

Request to the card authorization server:

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Transaction" Terminal_Type="2" Global_Type="ABC" Unit_ID="1" User_ID="1">
<Transaction>
<Account_Number>01.00008.00000006.0001</Account_Number>
<External_ID>123456</External_ID>
<External_Index>42206</External_Index>
<External_Date>2015-07-21</External_Date>
<Amount>100.50</Amount>
<Transaction_Time>2015-02-04 15:34:08.79 +03:00</Transaction_Time>
<Transaction_Life>2020-12-31</Transaction_Life>
<Transaction_Delay>2020-12-01</Transaction_Delay>
<Remarks>Transaction with credit delay and bonus lifetime</Remarks>
</Transaction>
</Message>


CODE

5.2. Debiting by account number
Request to the card authorization server:

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Transaction" Terminal_Type="2" Global_Type="ABC" Unit_ID="1" User_ID="1">
<Transaction>
<Account_Number>01.00008.00000006.0001</Account_Number>
<External_ID>123456</External_ID>
<External_Index>42206</External_Index>
<External_Date>2015-07-21</External_Date>
<Amount>-100.50</Amount>
<Remarks>Debit transaction</Remarks>
</Transaction>
</Message>

CODE

5.3. Crediting by card number and account type

Request to the card authorization server:

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Transaction" Terminal_Type="2" Global_Type="ABC" Unit_ID="1" User_ID="1">
<Transaction>
<Card_Code>123456789</Card_Code>
<Account_Type_ID>8</Account_Type_ID>
<External_ID>123457</External_ID>
<External_Index>42206</External_Index>
<External_Date>2015-07-21</External_Date>
<Amount>100.50</Amount>
<Remarks>Credit transaction</Remarks>
</Transaction>
</Message>

CODE

5.4. Debiting by card number and account type

Request to the card authorization server:

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Transaction" Terminal_Type="2" Global_Type="ABC" Unit_ID="1" User_ID="1">
<Transaction>
<Card_Code>123456789</Card_Code>
<Account_Type_ID>8</Account_Type_ID>
<External_ID>123457</External_ID>
<External_Index>42206</External_Index>
<External_Date>2015-07-21</External_Date> <Amount>-100.50</Amount>
<Remarks>Debit transaction</Remarks>
</Transaction>
</Message>

CODE

5.5. Additional transaction information

Transmission of additional details to the "Dop_Info" parameter (in order to match the XML format, it is recommended to convert XML into Base64 and add the Mode="Base64" attribute).

Request to the card authorization server:

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Transaction" Terminal_Type="2" Global_Type="ABC" Unit_ID="1" User_ID="1">
<Transaction>
<Account_Number>01.00008.00000006.0001</Account_Number>
<External_ID>123456</External_ID>
<External_Index>42206</External_Index>
<External_Date>2015-07-21</External_Date>
<Amount>50</Amount>
<Remarks>Credit transaction with additional information</Remarks>
<Dop_Info>
<![CDATA[Additional information, e.g., the list of dishes in a restaurant order, 
or the name and viewing time of a movie]]>
</Dop_Info>
</Transaction>
</Message>

CODE

5.6. Multiple transaction execution

Request to the card authorization server:

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Transaction" Terminal_Type="2" Global_Type="ABC" Unit_ID="1" User_ID="1">
<Transaction>
<Account_Number>01.00008.00000006.0001</Account_Number>
<External_ID>123456</External_ID>
<External_Index>42206</External_Index>
<External_Date>2015-07-21</External_Date> <Amount>-50</Amount>
<Remarks>Debit transaction</Remarks>
</Transaction> <Transaction>
<Account_Number>01.00007.00000001.0001</Account_Number>
<External_ID>123456</External_ID>
<External_Index>42206</External_Index>
<External_Date>2015-07-21</External_Date>
<Amount>100.50</Amount>
<Remarks>Credit transaction</Remarks>
</Transaction>
</Message>

CODE

5.7. Requesting the list of transactions ("Get transactions info")

The request implies getting additional information, received from a cash desk. The following principle of getting additional information is implemented: if the "Transaction_DopInfo" parameter is specified, a block of additional information will be returned. If "Transaction_DopInfo" is absent in the request, "Dop_Info" will reflect only the fact of additional information availability related to the given transaction (True/False).

If an empty "Client_ID" parameter is sent, the server automatically applies the software classifier identifier, determined based on "Terminal_Type". The "Unit_ID" parameter is also processed. In such a case, only "own" transactions will be displayed.

If an empty "Transaction_Parent" parameter is sent, the server selects transactions without a parent.

If the "Transaction_Life" parameter is specified, and the "Transaction_Life_From" or "Transaction_Life_To" values are set, the output list of transactions is displayed in the form of "hot bonuses". It means that the list includes only bonuses with a specified lifetime in ascending order. In this case, the "Account_Number" parameter is mandatory. If multiple transactions have accrued bonuses with equal lifetime values, these transactions are combined ("Transaction_ID" will display the list of identifiers), and only "Summ", "Summ_Spend" and "Transaction_Life" are left.

If the "Transaction_Bonuses" parameter is specified, the response will be complemented with information about accrued bonuses for each executed transaction.

The "Index" parameter starts the transaction sequence in descending sorting order from the current date to the first transaction (beginning with 1). If this parameter is not provided, the system starts the transaction transmission from the next item. For example, the first request showed, that there are 17 transactions, and received the first 10 of them. The second request (without "Index") received the transaction from 11th to 17th. After receiving a complete list of 17 transactions, the following request will receive an empty list. In order to get the list from the beginning, "Index=1" should be specified again.

"Account_Number", "Card_Code", "Transaction_ID", "Holder_ID", "External_ID" — one of these parameters should be mandatorily filled.

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Get transactions info" Terminal_Type="2" Global_Type="ABC" Unit_ID="1" User_ID="1">
<Transaction>
<Transaction_ID>1</Transaction_ID>
<Transaction_Type>1</Transaction_Type>
<Operation_Type></Operation_Type>
<Transaction_Parent></Transaction_Parent>
<Transaction_Life_From>2014-01-01</Transaction_Life_From>
<Transaction_Life_To>2014-12-31</Transaction_Life_To>
<Account_Class>1</Account_Class>
<Client_ID></Client_ID>
<Unit_ID>123</Unit_ID>
<External_ID>123456</External_ID>
<Holder_ID>123456789</Holder_ID>
<Card_Code>123456789</Card_Code>
<Account_Number>01.00008.00000006.0001</Account_Number>
<Date_From>2010-01-01</Date_From>
<Date_To>2010-01-31</Date_To>
<Index>5</Index>
<Count>10</Count>
<Include>Transaction_DopInfo, Transaction_Life, Transaction_Bonuses</Include> </Transaction>
</Message>

CODE

XML response format:

  Transactions (the list of transactions)

  Transaction (transaction information)
Division_ID (division code)

  Transaction_ID (transaction number)

  Transaction_Parent (parent transaction number)

  External_ID (external transaction number)

  Holder_ID (holder code)

  Transaction_Time (transaction execution time)

  Transaction_Delay (bonus accrual delay, with Operation_Type = 1)

  Transaction_Type (transaction type)
the last digit means the following (the interpretation depends on the operation type):

  "0" — the account level remains the same

  "1" — debit, or level decrease

  "2" — credit, or level increase

  Operation_Type (operation type)
the interpretation may depend on the transaction type
  "01" — transaction is waiting for balance calculation confirmation

  "02" — transaction has been accounted during the balance calculation

  "03" — reserved

  "04" — reserved

  "05" — reserved

  "06" — level transition transaction

  "07" — card blocking transaction

  "08" — card activation transaction

  "09" — card deactivation transaction

  "10" — card annulment transaction

  "11" — credit limit specification

  "12" — credit limit extension

  "13" — coupon generation

  "14" — coupon activation

  "15" — reserved

  "16" — reserved

  "17" — reserved

  "18" — coupon redemption
  "19" — not used

  "20" — entry capture

  "21" — internal movement capture

  "22" — exit capture

  "23" — card issue to the holder

  Operation_Type_Name (operation name)

  Account_Number (account number)

  Card_Code (card number)

  Summ (sum total)

  Client_ID (classifier code)

  Client_Type (classifier type)

  Client_Name (classifier name)

  Unit_ID (cash desk code)

  User_ID (cashier code)

  Remarks (comment)

  Dop_Info (additional information)

  "Yes" — additional information available

  "No" — no additional information available
  if the "Transaction_Life" parameter is set, the following tags will be returned
  Summ_Spend (sum total of accounted bonuses)
  Transaction_Life (bonus lifetime)

  if the "Transaction_Bonuses" parameter is set, the following tag will be returned
  Transaction_Bonuses (accrued bonuses for the given transaction)

 


5.8. Additional information on the previously executed transaction

Request to the card authorization server:

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Transaction" Terminal_Type="2" Global_Type="ABC" Unit_ID="1" User_ID="1">
<Transaction>
<Transaction_ID>1234567890</Transaction_ID>
<DopInfo>
<![CDATA[Additional information, e.g., the list of dishes in a restaurant order, 
or the name and viewing time of a movie]]>
</DopInfo>
</Transaction>
</Message>
CODE

5.9. Cancel operation

Request to the card authorization server:

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Transaction" Terminal_Type="10" Unit_ID="0" User_ID="0">
<Transaction Mode="Cancel">
<Unit_ID_Parent>2</Unit_ID_Parent>
<External_ID_Parent>102451</External_ID_Parent>
<External_Index_Parent>42206</External_Index_Parent>
<External_Date_Parent>2015-07-21</External_Date_Parent>
<Unit_ID>2</Unit_ID>
<External_ID>102455</External_ID>
<External_Index>42206</External_Index>
<External_Date>2015-07-21</External_Date> </Transaction>
</Message>

CODE

"External_ID_Parent", "External_Index_Parent" and "External_Date_Parent" should unambiguously identify the operation being returned.

  1. Working with holders

6.1. Adding holders ("Add holders")

If an "Include" is specified in the request, the response will contain the card holder response structure ("Get holder info").

If there is no "Include" in the request, the response will contain the identifiers of the edited or added elements. For example, when one address is added, its identifier will be obtained at the output (introduced for Internet applications).

Default values for the card and holder groups can be specified in the card authorization server configurator. Moreover, the configurator can contain the specification of accounts, required by the system, which will complement the list of accounts transmitted in the request.

The specification of a unique phone number imposes a restriction on the "Value" parameter in the list of contacts. It should correspond to the recommendations of the standard E.164

(http://ru.wikipedia.org/wiki/E.164). At this stage, the value should contain one "+" character and 11 to 15 digits.

In CRM 7 based on HTTP, an extension of this request is implemented, intended for work optimization.

When specifying the country, city and street values, names can be used instead of identifiers:

  • parameter names are put into operation in case of missing identifiers;
  • the country name can be used to search for its identifier; if there is no identifier, an error is displayed;
  • the city/street name can be used to search for their identifiers (if multiple identifiers are found, the first one is displayed); if there is no identifier, a new city/street is added.

Request to the card authorization server:

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Add holders" Terminal_Type="2" Global_Type="ABC" Unit_ID="1" User_ID="1">
<Include>Account, Holder_Image, Holder_Contact, Holder_Address, Holder_Relative, 
Holder_Contract, Holder_Card</Include>
<Image_Format Width="200" Height="150">JPEG</Image_Format>
<Account_Filter>
<Account_Class>2</Account_Class>
<Account_Type_ID>1</Account_Type_ID>
</Account_Filter>
<Holder> see below the request text format
</Holder>
</Message>

CODE

XML request format:

  Holder (holder information)

  Group_ID (group code) — Integer

  L_Name (last name) — String(60)

  F_Name (first name) — String(40)

  M_Name (middle/patronymic name) — String(40)

  Full_Name (full name) —
  CRM 5 — String(120)

  CRM 7 — String(140)

  External_Code (external code) —

  CRM 5 — String(20)

  CRM 7 — String(60)

  Unpay_Type_ID (non-payer code) — Integer

  Birth (date of birth) — Date

  Photo (JPG image, Base64) — String

  Gender (gender) — String

  "Male"

  "Female"

  Marital (marital status) — String

  "No" — single/unmarried

  "Yes" — married

  Language_ID (language code, e.g., #0419 — Russian) — Integer

  Auto_Change_Levels — String

  "True" — automatic level transition enabled

  "False" — automatic level transition disabled

  Smoke — String

  "No" — non-smoker

  "Yes" — smoker

  Verification — String

  "No" — not verified

  "Yes" — verified
  Remarks (comment) —
  CRM 5 — String(255)

  CRM 7 — String(500)

  Source (source) —
  CRM 5 — String(60)

  CRM 7 — String(120)

  INN — String(25)


  Cards

  Card (card information)

  Group_ID (group code) — Integer

  Card_Code (card number) — Int64

  Carrier_Data (magnetic tape information) — String(max)

  Password (password)

  Offered (date of issue) — Date
by default, the current server date is set

  Expired (date of expiry) — Date
by default, the current server date + 1 year is set

  Is_Confirm_Manager (manager confirmation required) — String

  "No" — no confirmation required

  "Yes" — confirmation required
  Status (card status) — String

  "Active"

  "Inactive" (default)

  "Blocked"

  "Issue" — physical issue



  Accounts (the list of accounts)

  Account (account)

  Account_Type_ID (account type code) — Integer

  Auto_Change_Levels — String

  "True" — automatic level transition enabled

  "False" — automatic level transition disabled

  Credit_Depth (credit limit) — Double

  Mode (mode value attribute)

  "Set" — credit limit setting (default)

  "Add" — credit limit extension

  Max (credit limit maximum value attribute)

  Account_Level_ID (account level code) — Integer



  Contacts

  Contact (contact information)
Type_ID (type) — Integer

  Value (value) — String(128)

  Notes (note) —
  CRM 5 — String(255)

  CRM 7 — String(500)

  Dispatch (permit for dispatch) — String

  "True" — allowed

  "False" — not allowed

  Deleted (deletion flag) — String

  "True" — delete

  "False" — do not delete
below, you can see the protocol extension for CRM 7 based on HTTP.   Value_Ext (external identifier for social media) — String(128)


  Addresses

  Address (contact information)
Type_ID (type) — Integer

  Country_ID (country) — Integer

  ZIP (postal code) — Integer

  Region (region) — String(40)

  City_ID (city) — Int64

  Street_ID (street) — Int64

  House (house) — String(10)

  Building (building) — String(10)

  Entry (entrance) — String(10)

  Floor (floor) — String(10)

  Apartments (apartment) — String(10)

  Entry_Code (entry phone code) — String(10)

  DopInfo (additional information) —

  CRM 5 — String(100)

  CRM 7 — String(500)

  Deleted (deletion flag) — String

  "True" — delete

  "False" — do not delete
below, you can see the protocol extension for CRM 7 based on HTTP.

  Country (country) — String(60)

  City (city) — String(60)

  Street (street) — String(100)


  Relatives (the list of relatives)

  Relative (relative)

  Relative_ID (relative identifier) — Int64

  Relative_Type_ID (relationship type code; the relation between the "Relative_ID" and the

"Holder_ID" being edited) — Integer


  Attributes (the list of holder attributes)

  Attribute

  Attribute_ID (attribute code) — Integer
Mode (setting mode attribute)

  "Set" — attribute setting

  "Clear" — attribute resetting



 

6.2. Editing holders ("Edit holders")

When a new account is added, the account type should be specified. When editing an account, its number should be specified (the editing at this stage implies setting and removing the automatic level transition flag).

When editing an address or a contact, the "Address_ID" and "Contact_ID" parameters should be filled. In case of adding, parameters are not specified in the request structure. If the "Delete" flag is set, the address or contact will be deleted.

If an "Include" is specified in the request, the response will contain the card holder response structure ("Get holder info").

If there is no "Include" in the request, the response will contain the identifiers of the edited or added elements. For example, when one address is added, its identifier will be obtained at the output (introduced for Internet applications).

If some data is not edited, it should not be specified in the request in order to avoid server overload. This is particularly critical for the card section, since the license is validated during its completion.

In CRM 7 based on HTTP, an extension of this request is implemented, intended for work optimization.

  • Instead of "Holder_ID", the phone number ("Phone") can be specified:

◦ if the Mode="Add" attribute is set, the mechanism of a new holder addition is triggered (if the given phone number is missing in the lists).

  • When specifying the country, city and street values, names can be used instead of identifiers:

◦ parameter names are put into operation in case of missing identifiers;

◦ the country name can be used to search for its identifier; if there is no identifier, an error is displayed;

◦ the city/street name can be used to search for their identifiers (if multiple identifiers are found, the first one is displayed); if there is no identifier, a new city/street is added.


Request to the card authorization server:

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Edit holders" Terminal_Type="2" Global_Type="ABC" Unit_ID="1" User_ID="1">
<Include>Account, Holder_Image, Holder_Contact, Holder_Address, Holder_Relative, 
Holder_Contract, Holder_Card</Include>
<Image_Format Width="200" Height="150">JPEG</Image_Format>
<Account_Filter>
<Account_Class>2</Account_Class>
<Account_Type_ID>1</Account_Type_ID>
</Account_Filter>
<Holder> see below the request text format
</Holder>
</Message>

CODE

XML request format:

  Holder (holder information)
Holder_ID (identifier) — Int64

  Group_ID (group code) — Integer

  L_Name (last name) — String(60)

  F_Name (first name) — String(40)

  M_Name (middle/patronymic name) — String(40)

  Full_Name (full name) —
  CRM 5 — String(120)

  CRM 7 — String(140)

  External_Code (external code) —

  CRM 5 — String(20)

  CRM 7 — String(60)

  Unpay_Type_ID (non-payer code) — Integer

  Birth (date of birth) — Date

  Photo (JPG image, Base64) — String

  Gender (gender) — String

  "Male"

  "Female"

  Marital (marital status) — String

  "No" — single/unmarried

  "Yes" — married

  Language_ID (language code, e.g., #0419 — Russian) — Integer

  Auto_Change_Levels — String

  "True" — automatic level transition enabled

  "False" — automatic level transition disabled

  Smoke — String

  "No" — non-smoker

  "Yes" — smoker

  Verification — String

  "No" — not verified
  "Yes" — verified

  Remarks (comment) —

  CRM 5 — String(255)

  CRM 7 — String(500)

  Source (source) —
  CRM 5 — String(60)

  CRM 7 — String(120)

  INN — String(25)


  Cards

  Card (card information)
Group_ID (group code) — Integer

  Card_Code (card number) — Int64

  Carrier_Data (magnetic tape information) — String(max)

  Password (password)

  Offered (date of issue) — Date

  Expired (date of expiry) — Date

  Is_Confirm_Manager (manager confirmation required) — String

  "No" — no confirmation required

  "Yes" — confirmation required


  Relatives (the list of relatives)

  Relative (relative)

  Relative_ID (relative identifier) — Int64

  Relative_Type_ID (relationship type code; the relation between "Relative_ID" and

"Holder_ID" being edited) — Integer


  Accounts (the list of accounts)

  Account (account)

  Account_Number (account number at the time of editing) — String

  Account_Type_ID (account type code, at the time of adding) — Integer

  Auto_Change_Levels — String

  "True" — automatic level transition enabled

  "False" — automatic level transition disabled

  Credit_Depth (credit limit) — Double

  Mode (mode value attribute)

  "Set" — credit limit setting (default)

  "Add" — credit limit extension

  Max (credit limit maximum value attribute)

  Account_Level_ID (account level code) — Integer


  Contacts

  Contact (contact information)

  Contact_ID (identifier, at the time of editing) — Int64

  Type_ID (type) — Integer

  Value (value) — String(128)

  Notes (note) —
  CRM 5 — String(255)

  CRM 7 — String(500)

  Dispatch (permit for dispatch) — String

  "True" — allowed

  "False" — not allowed

  Deleted (deletion flag) — String

  "True" — delete

  "False" — do not delete

  below, you can see the protocol extension for CRM 7 based on HTTP.

  Value_Ext (external identifier for social media) — String(128)



  Addresses

  Address (contact information)

  Address_ID (identifier, at the time of editing) — Int64

  Type_ID (type) — Integer

  Country_ID (country) — Integer

  ZIP (postal code) — String(40)

  Region (region) — String(40)

  City_ID (city) — Int64

  Street_ID (street) — Int64

  Metro_Station_ID (metro station) — Int64

  House (house) — String(10)

  Building (building) — String(10)

  Entry (entrance) — String(10)

  Floor (floor) — String(10)

  Apartments (apartment) — String(10)

  Entry_Code (entry phone code) — String(10)

  DopInfo (additional information) —

  CRM 5 — String(100)

  CRM 7 — String(500)

  Deleted (deletion flag) — String

  "True" — delete

  "False" — do not delete

  below, you can see the protocol extension for CRM 7 based on HTTP.

  Country (country) — String(60)

  City (city) — String(60)

  Street (street) — String(100)




  Attributes (the list of holder attributes)

  Attribute

  Attribute_ID (attribute code) — Integer

  Mode (mode setting attribute)

  "Set" — attribute setting

  "Clear" — attribute resetting


  Holders_Properties (the list of holder properties)

  Holder_Property

  Property_ID (property code) — Integer

  Value_ID (value code) — Integer

  If no value is provided, the property is cleared


6.3. Requesting holder information ("Get holder info")

Request to the card authorization server (request tags "Account_Filter", "Include" and "Image_Format": see 1.1 "Get card info"):

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Get holder info" Terminal_Type="123" Global_Type="ABC"> <Holder_ID>123456789</Holder_ID>
</Message>
CODE

XML response format (see also the XML response for "Get card info"):

  Holder

  Division_ID (division code)

  Division_Name (division name)

  Holder_ID (holder code)

  External_Code (external code)

  Unpay_Type_ID (non-payer code)

  Unpay_Type_Name (non-payer name)

  L_Name (last name)

  F_Name (first name)

  M_Name (middle/patronymic name)

  Full_Name (full name)
  Birth (date of birth)

  "Unknown" — not specified

  Gender (gender)

  "Unknown" — not specified

  "Male"

  "Female"

  Marital (marital status)

  "Unknown" — not specified

  "No" — single/unmarried

  "Yes" — married

  Dispatch_EMail (permit for an email dispatch)

  "True" — allowed

  "False" — not allowed

  Dispatch_SMS (permit for an SMS dispatch)

  "True" — allowed

  "False" — not allowed

  Smoke — String

  "No" — non-smoker

  "Yes" — smoker

  Verification — String

  "No" — not verified

  "Yes" — verified

  Language_ID (language code)

  "Unknown" — not specified

  Language_Name (language name)

  "Unknown" — not specified

  Remarks (comment)

  Accounts (the list of accounts, Include = Account)

  The "Account" may contain additional tags (see "Get card info")

  Account (account)
Status (account status)

  "Active"

  "Blocked"

  Block_Reason (the reason for blocking, if applicable)

  Account_Number (account number)
  Account_Class (account class)

  "1" — bonus account

  "2" — discount account

  "3" — debit account

  "4" — credit account

  "5" — funds spent

  "6" — membership

  "99" — user account

  Account_Type_ID (account type code)

  Account_Type_Name (account type name)

  Account_Debit_Enabled (the possibility of debiting the account)

  "Yes" — debit enabled

  "No" — debit disabled

  Account_Debit_Priority (account priority for debiting)

  Account_Debit_K (debit ratio for the classifier)
  Account_Credit_Enabled (the possibility of crediting the account)

  "Yes" — credit enabled

  "No" — credit disabled

  Account_Credit_Priority (account priority for crediting)

  Account_Credit_K (credit ratio for the classifier)

  Account_Level_ID (account level code)

  Account_Level_Name (account level name)

  Transaction_Debit_ID (debit transaction type)

  Transaction_Credit_ID (credit transaction type)

  Scheme_ID (rate scheme internal code)

  External_ID (rate scheme external code)
  Scheme_Name (rate scheme name)

  Base_Rate (basic interest rate)

  Create (account creation date)

  Credit_Depth (credit limit)

  Balance (balance, with reference to the debit ration for the classifier)
  Auto_Change_Levels (automatic transition between levels)

  "No" — unavailable

  "Yes" — available

  Time_ID (timing scheme code)

  Time_Name (timing scheme name)

  Current_Rate (current interest rate)

  Account_Code (rate scheme internal code)
  Account_Code_Ext (rate scheme external code)



  Holders_Relatives (the list of relatives, Include = Holder_Relative)

  Holder_Relative

  Holder_ID (holder code)

  Holder (relative information)

  Division_ID (division code)

  Holder_ID (holder code)

  L_Name (last name)

  F_Name (first name)

  M_Name (middle/patronymic name)

  Full_Name (full name)
  Birth (date of birth)
       "Unknown" — not specified

   

  Holders_Contracts (the list of holder contracts, Include = Holder_Contract)

  Holder_Contract

  Holder_ID (holder code)

  Contract (contract information)

  Contract_ID (contract code)
  Name (contract name)

  Type_ID (contract type)

  Type_Name (contract type name)

  Offered (valid-from date)

  Expired (valid-to date)

  Holders (the list of participants)

  Holder

  Division_ID (division code)

  Holder_ID (holder code)

  L_Name (last name)

  F_Name (first name)

  M_Name (middle/patronymic name)

  Full_Name (full name)
  Birth (date of birth)

  "Unknown" — not specified


  Holders_Images (the list of holder photos, Include = Holder_Image)

  Holder_Image

  Holder_ID (holder code)

  Photo (a Base64 image)

  Format (data format)

  "BMP" — Windows Bitmap (default)

  "JPEG" — Joint Photographic Experts Group


  Holders_Contacts (the list of holder contacts, Include = Holder_Contact)

  Holder_Contact

  Holder_ID (holder code)

  Contact (contact information)

  Deleted (deletion flag)

  "Yes" — deleted

  "No" — not deleted

  Contact_ID (contact code)

  Type_ID (type)

  Type_Code (external type code)

  Type_Name (type name)

  Value (value)

  Value_Ext (external identifier for social media)

  Notes (note)


  Holders_Addresses (the list of holder addresses, Include = Holder_Address)

  Holder_Address

  Holder_ID (holder code)

  Address (contact information)

  Deleted (deletion flag)

  "Yes" — deleted

  "No" — not deleted

  Address_ID (address identifier)

  Type_ID (type)

  Type_Name (name)

  Country_ID (country identifier)

  Country (country)

  ZIP (postal code)

  Region (region)

  City_ID (city identifier)

  City (city)

  Street_ID (street identifier)

  Street (street)

  Metro_Station_ID (metro station identifier)

  Metro_Station (metro station)
  House (house)

  Building (building)

  Apartments (apartment)

  DopInfo (additional information)


  Holders_Cards (the list of holder cards, Include = Holder_Card)

  Holder_Card

  Holder_ID (holder code)

  Card (card information)

  Card_Code (card number)

  Is_Virtual_Card (check for a virtual card)
"Yes"

  "No"

  Is_Confirm_Manager (manager confirmation required)
"Yes"

  "No"

  Status (card status)

  "Active"

  "Inactive"

  "Deleted"

  "Blocked"

  "Disabled"

  "Issue" — physical issue

  Block_Reason (the reason for blocking)

  Carrier_Data (magnetic tape information)

  Offered (date of maintenance)

  Expired (date of expiry)

  Group_ID (group code)

  Group_Name (group name)

  Holder_ID (holder code)

  Owner_ID (owner code)

   

6.4. Searching for holders ("Search holders 2")

Request to the card authorization server (in this example, the previous list is cleared first, then, all persons with the last name “Ivanov” and the patronymic name beginning with “Alex” are displayed in a list, including all names but those beginning with “D”).

The values in string fields (Login, L_Name, F_Name, M_Name, Full_Name, Phone, Email, City, Street, House) may contain the following substitute characters:

  "?" — one random character;

  • "*" — multiple random characters.

For example:
the last name search formatted as "St?lov" will result in "Stulov", "Stolov", etc.
the first name search formatted as "Al*" will result in "Alexey", "Alexander", "Alla", etc.

Integer values in the corresponding fields (Card_Code) may contain the following substitute characters:

  "?" — substitutes one random character;

  • "*" — substitutes multiple random characters;

  "[" or "]" — the numbers at the ends of the given range are included in the range;
"(" or ")" — the numbers at the ends of the given range are excluded from the range;
"or" — subset join;
"and" — subset intersection;
"not" — exclusion from subset.
Example of a card search: 

  "1?? and *0 or 55" — all cards from the first hundred, the numbers of which end with "0", and the 55th card.

  "[1..100)" — all cards from the first hundred, excluding the 100th card.

  ">= 1000 and < 5000" — all cards greater than 1000 (inclusive), but less than 5000.

The values in date fields (Birth_Day) may contain zero characters:

For example:
a search by February — "0000-02-00" — will display all persons that were born in February, etc.

Inside the <Item Mode="Add"> section, the search is based on the "AND" principle. Consecutive sections add the found holder into the general list.

<Include> may contain sorting fields: Sort_L_Name, Sort_F_Name, Sort_M_Name, Sort_Full_Name, Sort_Birth. When sorting by the date of birth, empty dates will be at the end of the list.

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Search holders 2" Terminal_Type="2" Global_Type="ABC" Unit_ID="1" User_ID="1">
<Include>Account, Holder_Image, Holder_Contact, Holder_Address, Holder_Relative, 
Holder_Contract, Holder_Card</Include>
<Image_Format Width="200" Height="150">JPEG</Image_Format>
<Account_Filter>
<Account_Class>2</Account_Class>
<Account_Type_ID>1</Account_Type_ID>
</Account_Filter>
<Count>25</Count>
<Index>1</Index>
<Item Mode="Clear"/>
<Item Mode="Add">
<Holders>
<Login Value="C*.000?55"/>
<External_Code Value="Alex*"/>
<L_Name Value="Ivan*"/>
<F_Name Value="Alexander"/>
<M_Name Value="Ivanovitch"/>
<Full_Name Value="Alex*"/>
<Birth_Day Value_From="0000-02-01" Value_To="0000-02-07"/>
<Image Value="True"/>
<Group_ID Value="32" />
</Holders>
<Cards>
<Card_Code Value="12345*"/>
<Carrier_Data Value="987654"/>
<Group_ID Value="27" />
<Group_ID Value="15" />
</Cards>
<Contacts>
<Phone Value="12345" IsNumber="True"/>
<EMail Value="mail@mail.ru"/>
</Contacts>
<Addresses IsDeleted="True">
<City Value="Moscow"/>
<Street Value="B.Pochtovaya"/>
<House Value="20"/>
</Addresses>
<!--- relevant since CRM 7.06.05.000 --> <Contracts>
<Name Value="*_2016_1235"/>
<Type Value="17"/>
<Offered Value_From="0000-02-01" Value_To="0000-02-07"/>
<Expired Value_From="0000-03-01" Value_To="0000-03-07"/> <Signature Value_From="0000-01-01" Value_To="0000-01-31"/>
<!--- "Signature" can also be queried about the signature availability: Value="true" --> <Blocked Value="true"/>
</Contracts>
</Item>
<Item Mode="Del">
<Holders>
<F_Name Value="D*"/>
</Holders>
</Item> </Message>

CODE

This sample request outputs 25 holders, starting with the 1st. If the "Count" parameter is not specified, it will be set to 50 by default. It should be noted that after the card authorization server restart, search data sets are reset.

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Search holders 2" Terminal_Type="2" Global_Type="ABC" Unit_ID="1" User_ID="1">
<Count>10</Count>
<Index>31</Index>
</Message>

CODE

Upon receiving the <Item Mode="Clear"/> section in the request, the server initiates the generation of a new data set. The XML response will contain a "Search_GUID", which should be specified in further requests for the purpose of working with the given search data set.

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Search holders 2" Terminal_Type="2" Global_Type="ABC" Unit_ID="1" User_ID="1">
<Search_GUID>{46666E09-AC6B-4B5A-B282-7B55E82571BD}</Search_GUID>
<Count>10</Count>
<Index>31</Index> </Message>

CODE

In order to optimize the speed of working, it is recommended to clear the data set at the end of operation, i.e. execute the following request.

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Search holders 2" Terminal_Type="2" Global_Type="ABC" Unit_ID="1" User_ID="1">
<Search_GUID>{46666E09-AC6B-4B5A-B282-7B55E82571BD}</Search_GUID> <Item Mode="Clear"/>
</Message>

CODE

If the request does not imply further processing of the data set, the clearing section should be specified at the end. Relevant since CRM 5.9.5.3 and CRM 7.9.0.0

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Search holders 2" Terminal_Type="2" Global_Type="ABC" Unit_ID="1" User_ID="1">
<Include>Holder_Contact, Holder_Address, Holder_Card, Holder_NoCount</Include> 
<Count>100</Count>
<Index>1</Index>
    <Item Mode="Clear"/>
    <Item Mode="Add">
        <Contacts>
<Phone Value="+89991112233*" IsNumber="True"/>
        </Contacts>
    </Item>
    <Item Mode="Clear"/> </Message>

CODE
  1. Working with manuals

7.1. Requesting information on account types ("Get accounts types info")

Request to the card authorization server:

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Get accounts types info" Terminal_Type="2" Global_Type="ABC"> </Message>

CODE

XML response format:

  Accounts_Types

  Account_Type (account type information)

  Status (account type status)

  "Active"

  "Deleted"

  "Blocked"

  Account_Type_Class (account type class)

  "1" — bonus account

  "2" — discount account

  "3" — debit account

  "4" — credit account

  "5" — funds spent

  "6" — membership

  "99" — user account

  Account_Type_ID (account type code)

  Account_Type_Name (account type name)

  Date_From (valid-from date)

  Date_To (valid-to date)

7.2. Requesting information on countries ("Get countries info")

Request to the card authorization server:

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Get countries info" Terminal_Type="2" Global_Type="ABC"> </Message>

CODE

XML response format:

  Countries

  Country (country information)
Country_ID (country code)
Country_Name (country name)


7.3. Requesting information on card groups ("Get cards groups info")

Request to the card authorization server:

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Get cards groups info" Terminal_Type="2" Global_Type="ABC"> </Message>

CODE

XML response format:

  Groups

 Group (group information)
Group_ID (group code)

Group_Name (group name)

7.4. Requesting information on holder groups ("Get holders groups info")

Request to the card authorization server:

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Get holders groups info" Terminal_Type="2" Global_Type="ABC"> </Message>

CODE

XML response format:

  Groups

  Group (group information)
Group_ID (group code)

  Group_Name (group name)

 

7.5. Requesting information on contact types ("Get contacts types info")

In order to get a default value, the <Default>Yes</Default> tag should be specified.
Request to the card authorization server:

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Get contacts types info" Terminal_Type="2" Global_Type="ABC">
</Message>

CODE

  Contacts_Types

  Contact_Type (contact type information)

  Contact_Type_ID (contact type code)

  Contact_Type_Code (contact type external code)

  Contact_Type_Name (contact type name)

  Contact_Type_EMail (contact check for being an email address)

  "Yes"

  "No"

  Contact_Type_Phone (contact check for being a phone number)

  "Yes"

  "No"

  Is_Unique (phone uniqueness flag; optional attribute)

  Contact_Type_Skype (contact check for being a Skype number)

  "Yes"

  "No"

  Contact_Type_Social_Network (contact check for being a social network)

  "Yes"

  "No"

  Contact_Type_Dispatch (permit for dispatch)

  "Yes" — allowed

  "No" — not allowed

7.6. Requesting information on address types ("Get addresses types info")

In order to get a default value, the <Default>Yes</Default> tag should be specified.
Request to the card authorization server:

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Get addresses types info" Terminal_Type="2" Global_Type="ABC">
</Message>
  

Addresses_Types
  Address_Type (address type information)
  Address_Type_ID (address type code)
  Address_Type_Name (address type name)

CODE

 

7.7. Requesting information on divisions ("Get divisions info")

Request to the card authorization server:

 

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Get divisions info" Terminal_Type="2" Global_Type="ABC">
</Message>

CODE

Divisions

  Division (division information)
  Division_ID (division code)

  Division_Name (division name)

  Division_Full_Name (division full name)

  Division_Main (main division flag)

  "Yes" — main division

  "No" — not main division

7.8. Requesting information on cities ("Get cities info")

The "Country_ID" parameter is optional. In order to get a default value, the "Default" parameter should be specified; in this case, the "City_ID" value will be ignored, if it is provided in the request.

Request to the card authorization server:

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Get cities info" Terminal_Type="2" Global_Type="ABC">
<Country_ID>123</Country_ID>
<Default>Yes</Default>
</Message>
  Cities
  City (city information)
  Country_ID (country code)
  City_ID (city code)
  City_Name (city name)
  
CODE

7.9. Requesting information on streets ("Get streets info")

The "City_ID" parameter is optional. In order to get a default value, the "Default" parameter should be specified; in this case, the "City_ID" value will be ignored, if it is provided in the request.

Request to the card authorization server:

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Get streets info" Terminal_Type="2" Global_Type="ABC">
<City_ID>123</City_ID>
<Default>Yes</Default>
</Message>

CODE

  Streets

  Street (street information)

  City_ID (city code)

  Street_ID (street code)

  Street_Name (street name)

  Post_Code (postal code)

The format is optimized in terms of volume (up to a triple volume reduction). In this implementation, the "City_ID" parameter is mandatory.

Request to the card authorization server:

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Get streets info" Terminal_Type="2" Global_Type="ABC" Query_Version="2"> <City_ID>123</City_ID>
</Message>

CODE

  Streets

  City_ID (city code)

  Street (street information)
  ID (street code)

  Name (street name)

  Post_Code (postal code; the attribute is available in case of filling)
7.10. Requesting information on card properties ("Get cards properties info")

Request to the card authorization server:

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Get cards properties info" Terminal_Type="2" Global_Type="ABC">
</Message>

CODE

  Properties

  Property (property information)

  Property_ID (property code)

  Property_Code (external property code)

  Property_Name (property name)

  Values (the list of applicable values)

  Value (value information)
  Value_ID (value code)

  Value_Type (value type)

  "None" — not specified

  "Integer" — an integer number: 1234

  "Float" — a real number: 12.34

  "String" — a string

  "Date" — a date: 2014-12-31

  "Time" — time: 12:34:56

  "DateTime" — date and time: 2014-12-31T12:34:56

   Value_Value (external value)

   Value_Name (value name)


7.11. Requesting information on card holder properties ("Get holders properties info")

Request to the card authorization server:

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Get holders properties info" Terminal_Type="2" Global_Type="ABC"> </Message>

CODE

The structure is shown in 7.10.

7.12. Requesting information on metro stations ("Get metro stations info")

The "City_ID" parameter is optional.

Request to the card authorization server:

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Get metro stations info" Terminal_Type="2" Global_Type="ABC"> <City_ID>123</City_ID>
</Message>
  Metro_Stations
  Metro_Station (metro station information)
  City_ID (city code)
  Metro_Station_ID (metro station code)
  Metro_Station_Name (metro station name)

CODE

7.13. Requesting information on timing schemes ("Get timing schemes info")

Implemented for CRM 7 based on HTTP.

Request to the card authorization server:

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Get timing schemes info" Terminal_Type="2" Global_Type="ABC">
</Message>

CODE

  Timing_Schemes

  Timing_Scheme (timing scheme information)
  Timing_Scheme_ID (timing scheme code)

  Timing_Scheme_Name (timing scheme name)

  Timing_Scheme_Details (the list of time entities)

  Timing_Scheme_Detail

  Time_ID (time code)

  Name (time entity name)

  Date_From (period start date and time)

  Date_To (period end date and time)

  Time_From (restriction start time within a period)

  Time_To (restriction end time within a period)
  Months (restriction mask for months)

  "0x0001" — January

  "0x0002" — February

  "0x0004" — March

  "0x0008" — April

  "0x0010" — May

  "0x0020" — June

  "0x0040" — July

  "0x0080" — August

  "0x0100" — September

  "0x0200" — October
"0x0400" — November

  "0x0800" — December

  Week_Days (restriction mask for weekdays)

  "0x0001" — Monday

  "0x0002" — Tuesday

  "0x0004" — Wednesday

  "0x0008" — Thursday

  "0x0010" — Friday

  "0x0020" — Saturday

  "0x0040" — Sunday

  Week_Numbers (restriction mask for week numbers)

  "0x0001" — 1st week of the month

  "0x0002" — 2nd week of the month

  "0x0004" — 3rd week of the month

  "0x0008" — 4th week of the month

  "0x0010" — 5th week of the month

  "0x0020" — 6th week of the month

  Birthday (take the card holder date of birth into consideration)
  Before (days until the date of birth)

  After (days after the date of birth)

7.14. Requesting information on contract types ("Get contracts types info")

Request to the card authorization server:

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Get contracts types info" Terminal_Type="2">
</Message>
  Contracts_Types
  Contract_Type (contract type information)
  Contract_Type_ID (contract type code)
  Contract_Type_Name (contract type name)
  Contract_From (contract validity start date)
  Contract_To (contract validity end date)
  Contract_Notes (comment)

CODE
  1. New holder authorization and registration

8.1. Registering card holders ("Registration")

The registration is performed in 2 stages.

At the first stage, a request form with personal data is submitted: full name, mobile phone number, card number (optional). The authorization code is sent by SMS to the specified phone number. If an E-mail is specified instead of a phone number, the authorization code will be emailed to the given address. The message subject and body (in Base64 format) should be specified in "EMail_Subject" and "EMail_Body" parameters, respectively. If the "Include" tag is specified with the "Code_Timeout", the response will contain the authorization code lifetime in minutes.

The second stage implies the authorization code activation, following which the information about the card number and password will be sent to the given phone number. If required, the “Include” tag may be specified in the request, so that the response would contain the card holder information.

If no card is specified, it will be issued to the holder automatically. For a full functionality of the created card and holder, the card holder data should be edited (account creation is required). Is_Virtual_Card — flag for a virtual card registration.

Request to the card authorization server (stage 1):

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Registration" Terminal_Type="2" Global_Type="ABC" Unit_ID="1" User_ID="1">
	  	<Login>+7(123)456-78-90</Login>
	    	 <L_Name>Last name</L_Name>
	       	<F_Name>First name</F_Name>
	       	<M_Name>Patronymic name</M_Name>
	       	<Full_Name>Full name</Full_Name>
	 	<Card_Code>1234567890</Card_Code>
	 	<EMail_Subject></EMail_Subject>
	 	<EMail_Body Mode="Base64"></Email_Body>
	 	<Include>Code_Timeout</Include>
	 	<Include></Include>
</Message>

CODE

Request to the card authorization server (stage 2):

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Registration" Terminal_Type="2" Global_Type="ABC" Unit_ID="1" User_ID="1">
	 	<Login>+7(123)456-78-90</Login>
	 	<Auth_Code>t0bZ562C8Q</Auth_Code>
</Message>

CODE

8.2. Restoring a master password ("Setting password")

In the first step of the password restoration procedure, a password change confirmation code is sent to the phone number (E-mail) provided in the request.

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Setting password" Terminal_Type="2" Global_Type="ABC" Unit_ID="1" User_ID="1">
	 	<Login>+7(123)456-78-90</Login>
</Message>

CODE

In the second step, the confirmation code, login and the password itself are sent. The "Password" tag is optional; if absent, a new code will be generated automatically.

When changing the password via E-mail, the message header and body should be specified. The PASSWORD key word will be replaced with a new password.

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Setting password" Terminal_Type="2" Global_Type="ABC" Unit_ID="1" User_ID="1">
	 	<Login>support@ucs.ru</Login>
	 	<Password>1</Password>
	   	   <EMail_Subject>Password change</EMail_Subject>
	       	<EMail_Body>Password has been changed: PASSWORD</EMail_Body>
</Message>

CODE

8.3. Account authorization with a master password of the holder ("Authorization")

The login procedure with the use of a master password implies an optional identification of the holder by their card number, phone number, or E-mail address:

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Authorization" Terminal_Type="2" Global_Type="ABC" Unit_ID="1" User_ID="1">
<Card_Code>123456789</Card_Code>
<Phone>+7(123)456-78-90</Phone>
<EMail>support@ucs.ru</EMail>
<Password>1</Password>
	 	<Include></Include>
</Message>

CODE

8.4. Account authorization with an authorization code ("Login")

Login procedure with the use of an authorization code sent by SMS to the specified phone number (or via E-mail):

Request to the card authorization server (stage 1):

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Login" Terminal_Type="2" Global_Type="ABC" Unit_ID="1" User_ID="1"> <Login>+7(123)456-78-90</Login>
	 	<Include>Code_Timeout</Include>
</Message>

CODE

If the "Code_Timeout" parameter is specified, the response will contain the code lifetime and the number of attempts to use it:

 <Login Message_ID="0">
 <Code_Timeout>180</Code_Timeout>
 <Code_Use>5</Code_Use>
 <Message>A one-time password has been sent to you.

CODE

It can be used 5 times within 180 seconds.</Message> </Login>

Request to the card authorization server (stage 2):

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Message Action="Login" Terminal_Type="2" Global_Type="ABC" Unit_ID="1" User_ID="1">
	 	<Login>+7(123)456-78-90</Login>
	 	<Auth_Code>123456</Auth_Code>
</Message>

CODE

When the "Auto_Registry" attribute is specified (relevant for both steps), the login request will register the contact, if it has not been registered yet ("Card_Code" is optional).  Is_Virtual_Card — flag for a virtual card. For example:

<Message Action="Login"  Terminal_Type="2" Global_Type="ABC" Unit_ID="1" User_ID="1">
<Login Auto_Registry="True">+7(123)456-78-90</Login>
	 	<Is_Virtual_Card>Yes</Is_Virtual_Card >
	 	<Card_Code>1234567890</Card_Code>
	 	<Include></Include>
</Message>

CODE

Note A

In case of a successful execution, the "200 OK" response is returned.

The list of system errors:

  • Message format incorrect
  • Parameter incorrect
  • Message type incorrect
  • Invalid message
  • Database access error

"404 Database access error" breakdown

SAC-0001 Unsuccessful connection to the database

SAC-0002 Department not determined

SAC-0003 Invalid XML request format

SAC-0004 Classifier ["A"] entered incorrectly

SAC-0005 Blockage time entered incorrectly

SAC-0006 Authorization code determination error

SAC-0007 Account type not determined [ID=X]

SAC-0008 Account type "B" deleted

SAC-0009 Account type "B" inactive

SAC-0010 Account type "B" is missing for classifier "A"

SAC-0011 Account type "B" has no factor determined for classifier "A"

SAC-0012 Card number ["C"] entered incorrectly

SAC-0013 Account type entered incorrectly [ID=X]

SAC-0014 Card "C" not found in the system

SAC-0015 Account "D" of card "C" blocked

SAC-0016 Account "D" blocked

SAC-0017 Card "C" blocked

SAC-0018 Considering the overdraft the operation sum exceeds the limit

SAC-0019 Fund blockage means a term of blocking the funds

SAC-0020 Account "D" of card "C" not found

SAC-0021 Account "D" not found

SAC-0022 Account "D" has no account type determined

SAC-0023 Fund blockage means writing off funds

SAC-0024 A positive sum means fund crediting

SAC-0025 A negative sum means writing off funds

SAC-0026 Confirmation of the fund blockage means writing off funds

SAC-0027 Unblocking funds means fund crediting

SAC-0028 Authorization code "Z" not found

SAC-0029 Multiple transactions found with the authorization code "Z"

SAC-0030 Incorrect account ["D"] specified

SAC-0031 Batch contains fund blocking transactions for the same account

SAC-0032 Database error when attempting to implement the transaction (not used)

SAC-0033 Database operation error

SAC-0034 Operation with accounts belonging to other departments are not allowed

SAC-0035 Level not determined for account "D"
SAC-0036 Transition conditions set incorrectly

SAC-0037 No information about the level

SAC-0038 Threshold account not found

SAC-0039 Not enough funds on the threshold account

SAC-0040 Further transition not available

SAC-0041 Threshold account is blocked

SAC-0042 Write-off account not found

SAC-0043 Write-off account blocked

SAC-0044 Not enough funds on the account for a write-off

SAC-0045 Invalid reason for fund transfer

SAC-0046 Unknown error: error text

SAC-0047 The entered level is already set

SAC-0048 Entered level is missing in the transit schema

SAC-0049 Currently, the card validity does not allow the execution of operations

SAC-0050 No need for a decrease to the next level

SAC-0051 Error when forming an account type list

SAC-0052 Error when forming a country list

SAC-0053 Error when forming a group list

SAC-0054 Error when forming a contact type list

SAC-0055 Error when forming an address type list

SAC-0056 Required field is empty: X

SAC-0057 Card "X" already exists in the system

SAC-0058 Error when generating an identifier: X

SAC-0059 Account class [ID=X] not determined by the account type

SAC-0060 No level determined for account type "D"

SAC-0061 Card group [ID=X] not determined

SAC-0062 Owner group [ID=X] not determined

SAC-0063 The subscription period of account type "D" does not allow account creation

SAC-0064 Contact type [ID=X] not determined

SAC-0065 Address type [ID=X] not determined

SAC-0066 Card "C" inactive

SAC-0067 Status of card "C" unknown

SAC-0068 Date entered incorrectly: 99.99.9999

SAC-0069 Account type "B" is blocked for classifier "A"

SAC-0070 Status of card "C" is already determined

SAC-0071 Card "C" is annulled

SAC-0072 Multiple search results for card "C"

SAC-0073 Operation with the card is not allowed, since card "C" has no owner

SAC-0074 Customer ID [ID=X] entered incorrectly

SAC-0075 Customer "B" not found

SAC-0076 Multiple search results for customer "B"

SAC-0077 Card "B" already belongs to a customer

SAC-0078 Operation with cards belonging to other departments are not allowed

SAC-0079 Department prefix not found (not used)

SAC-0080 Account number "A" not found

SAC-0081 Multiple search results for account "A"

SAC-0082 Contact "A" not found

SAC-0083 Address "A" not found

SAC-0084 Notification of subscribers about the completion of the transaction unsuccessful

SAC-0085 Implementation of further transactions done by the subscribers

SAC-0086 City [ID=X] not determined

SAC-0087 Street [ID=X] not determined

SAC-0088 Country [ID=X] not determined

SAC-0089 Editing data of owners belonging to other departments is not allowed

SAC-0090 It is not allowed to edit more than A record(s)

SAC-0091 Card number or the password are entered incorrectly

SAC-0092 Phone number ["A"] entered incorrectly

SAC-0093 Error when sending the authorization code by SMS

SAC-0094 Unable to confirm the specified card or find a free card
SAC-0095 Phone number "А" not found in the lists of contacts
SAC-0096 Phone number "A" already exists in the lists of contacts.

It is not allowed to maintain the same number more than %s time(s).

Contact the administrator.

SAC-0097 X additional information record(s) found for transaction Z

SAC-0098 X records found with promotion A parameters for transaction Z (link: Y)

SAC-0099 Error when generating a list of relative types
SAC-0100 You have completed the registration procedure: card number X.

Unable to send the password by SMS due to technical problems.

Please, contact the support desk, or use the password restoration option.

SAC-0101 Query name entered incorrectly

SAC-0102 Relationship type [ID="A"] not determined

SAC-0103 Transaction not found

SAC-0104 Sum entered incorrectly: A

SAC-0105 Attempt to return an amount (A), greater than the receipt total (B) with reference to the previous refunds (C)

SAC-0106 Black list element [ID=A] not determined

SAC-0107 Error when generating the black list
SAC-0108 Error when generating a list of streets

SAC-0109 Error when forming a town list

SAC-0110 Error when forming a coupon type list

SAC-0111 Classifier blocked ["A"]

SAC-0112 Coupon not found in the system ["A"]

SAC-0113 Error when generating a list of coupon types

SAC-0114 Coupon type [ID="A"] not determined
SAC-0115 Classifier ["A"] not determined

SAC-0116 Multiple search results for coupon in the system ["A"]

SAC-0117 Coupon redemption is not allowed by this classifier

SAC-0118 Coupon used

SAC-0119 Coupon realization is not allowed by the validity period

SAC-0120 Coupon redemption is restricted by its validity

SAC-0121 Automatic operation server not supported
SAC-0122 Email "A" already exists in the lists of contacts.

It is not allowed to maintain the same Email more than X time(s).

Contact the administrator.

SAC-0123 Card "A" is not a virtual card

SAC-0124 Multiple search results for contact "A"

SAC-0125 The owner does not have a virtual card

SAC-0126 The department has no card ranges

SAC-0127 Authorization missing: A

SAC-0128 Unable to generate an authorization code.

Repeat the request.

SAC-0129 Promotion ID [ID=A] entered incorrectly

SAC-0130 Promotion "A" not found

SAC-0131 Promotion "A" configured incorrectly

SAC-0132 Promotion "A" inactive (check the promotion validity and schedule)

SAC-0133 Promotion "A": B

SAC-0134 Unable to generate a coupon code.

Repeat the request.

SAC-0135 Contact [ID=A] unique type not determined

SAC-0136 Phone number entered incorrectly for the virtual card ["A"]

SAC-0137 Contact ["A"] entered incorrectly

SAC-0138 The list of classifiers for the coupon redemption is not determined

SAC-0139 Owner is blacklisted [ID=A]

SAC-0140 Contact A of owner B is blacklisted

SAC-0141 Contact A is blacklisted

SAC-0142 Address A of owner B is blacklisted

SAC-0143 Address A is blacklisted

SAC-0144 Error when forming a list of card properties

SAC-0145 error when forming a list of card owner properties

SAC-0146 Property [ID=A] not determined

SAC-0147 Error when forming a subway station list

SAC-0148 Metro station [ID=A] not determined
SAC-0149 Multiple search results for address "A"

SAC-0150 Multiple search results for promotion "A"

SAC-0151 The coupon is already activated

SAC-0152 Message type [A] not determined

SAC-0153 Message text is entered incorrectly

SAC-0154 Holder is a required field

SAC-0155 Holder "A" not found

SAC-0156 Holder can not be changed

SAC-0157 The password may contain the following characters: 0..9, A..z, _

SAC-0158 Card "A" is being issued to the owner

SAC-0159 Card range of card "A" not found

SAC-0160 Unable to assign card "A" to owner "B"

SAC-0161 Card "A" cannot be used by this classifier

SAC-0162 API use of "RKeeper CRM" is not allowed

SAC-0163 Message header is entered incorrectly

SAC-0164 Limit of simultaneous card issuing has been exceeded

SAC-0165 Coupon realization is not allowed due to nominal differences

SAC-0166 Password not set

SAC-0167 A one-time password has been sent to you. It can be used X time(s) within A seconds.
SAC-0168 One-time password entered incorrectly.

It can be used again X time(s) within A seconds.

SAC-0169 No attempts left to enter the one-time password. Another one-time password can be generated in A seconds
SAC-0170 Error when sending an E-mail.

SAC-0171 One-time password generation required

SAC-9801 RKeeper_CRM.dll initialization unsuccessful

SAC-9802 Card server operation error

SAC-9803 RKeeper CRM does not support this object

SAC-9804 Realization of the coupon is not allowed at this cash register

SAC-9805 A card without an owner can not be used

SAC-9806 No accounts that can be used at the cash register are assigned to the card

SAC-9990 Card number "A" exceeds the allowed value limit

SAC-9991 Query access denied (the required Session parameter is invalid)

SAC-9992 Request received without the required parameters, or these are specified incorrectly
SAC-9993 Access to request denied

SAC-9994 Value A exceeds the allowed value B

SAC-9995 Access temporarily denied - the import process has been started

SAC-9996

SAC-9997 Database operation error

SAC-9998 Software version A does not match the database version B

SAC-9999 License agreement violated