General information
Stored credential transactions (COF) provides the simple way to make the subsequent operations with the card data that stored during the initial operation.
The initial operation is carried out with the obligatory receipt of the payer's consent to store of card details for subsequent operations.
The initial operation can be:
- financial transaction - with card verification and following payment;
- registration transaction - with card verification without a following payment.
The initial operation is carried out using a conventional bankcard, or using a mobile device tokenization system, for example, Apple Pay, Samsung Pay or Google Pay.
In any case, verification by one of the possible ways (CVC2 and 3dS or using a mobile device) is required for the initial COF operation.
Subsequent operations can be carried out after the successful initial operation with the obligatory consent of the payer to the further use of card data. Subsequent operations are carried out without any verification.
CIT COF operations
Subsequent operations can be initiated by the payer. These operations are called «Customer Initialized Transaction» (CIT).
The One Click program is used to implement CIT COF operations in IPS Assist.
By participating in the program, the company maintains its database of customers, giving them an unique number (CustomerNumber), while the Assist system stores the encrypted credit card data corresponding to those merchant customers (CustomerNumber).
While performing of order payment, the customer gets an offer to save the card for future payments using the One Click program.
The One Click program (see the «One Click Program» document) allows a regular customer of a merchant to make new purchases without entering card data. The payment requires only confirmation by the CVC2 code. However, if the initial COF operation is successful, the CVC2 code will not be requested in the subsequent operations.
To start use the COF operations the merchant should send request to support team support@assist.ru. The request should contain the merchant identifier (Merchant_ID).
Since unique numbers in the customer's database of the merchant (CustomerNumber) are generated and stored on the side of the merchant, it should pay special attention to protecting this data from hacking. It is necessary to increase the protection of personal data on the side of the merchant with the help of modern means (two-factor authentication for customers when entering the merchant's personal store, increased requirements for client passwords by security level, periodic updating of client passwords, etc.).
If the customer agrees to save the card, and proceed the successful payment then the IPS Assist generates a token - a unique card identifier that is stored in the system.
After the customer completes the payment for the order, a message with the payment parameters can be sent to the server of the merchant using the HTTP POST or SOAP method (for more details, see section 3.5 of the document «Setting up the technical interaction with IPS Assist») or the merchant can request the payment results by calling the orderresult web service.
In this case, an additional parameter appears in the list of payment parameters:
Name | Description |
token | The unique identifier of the saved customer card |
When the merchant builds the next order, it is possible to redirect to the IPS Assist payment page to pay with the earlier saved card. In this case, the merchant must send order data with a unique customer number, i.e. in addition to the authorized request parameters, it is necessary to transfer the CustomerNumber. All actions related to payment by a saved card are performed on the Assist side.
If for any reason it is more convenient for the merchant to independently display an offer to the customer to pay the order with a previously saved card (on its website or in a specialized mobile application), then in order to use CIT COF, the merchant has to call the Token Pay payment web-service.
The request URL for transfer the encrypted payment data block:
https://<SERVER_NAME>/pay/tokenpay.cfm ,
As <SERVER_NAME> you should use the received from support service (support@assist.ru) value as the domain name.
List of request parameters:
Parameter | Mandatory field | Adopted values | Default value | Description |
Merchant_ID | Yes | Number | The enterprise identifier in IPS Assist | |
Login | Yes | 8-20 characters | Login in IPS Assist (Latin letters, digits and symbol _) | |
Password | Yes | 8-20 characters | Password in IPS Assist (Latin letters and digits) | |
OrderNumber | Yes | 128 characters | Order number in the merchant payments system | |
OrderAmount | Yes | Number, 15 digits (delimiter: '.') | Payment amount, in original currency (e.g., 10.34). | |
OrderCurrency | No | 3 characters | Currency of legal entity/enterprise | Code of currency of the OrderAmount |
OrderComment | No | 256 characters | Comment. | |
Delay | No | 0 – one-stage operation 1 – double-stage operation | 0 | Attribute of a bankcard authorization for the double-stage operation mode. |
Language | No | RU – Russian, EN – English | Language of legal entity/enterprise | Language of authorized pages |
ClientIP | No | Maximum of 15 digits, 4 delimiters «.» | IP-address of the customer | |
TokenType | No | 5 – Assist; | 1 | Payment Token Type Identifier |
PaymentToken | No | JSON | Payment Token {"Token":"<UUID>", "CustomerNumber":"<CustomerNumber>"} | |
Lastname | No | 70 characters | Customer's last name. | |
Firstname | No | 70 characters | Customer's first name. | |
Middlename | No | 70 characters | Customer's middle name. | |
No | 128 characters | Customer's e-mail. | ||
Address | No | 256 characters | Customer's address. | |
HomePhone | No | 64 characters | Customer's home phone number. | |
WorkPhone | No | 20 characters | Customer's work phone number. | |
MobilePhone | No | 20 characters | Customer's mobile phone number. | |
Fax | No | 20 characters | Customer's fax number. | |
Country | No | 3 characters | Customer's country. | |
State | No | 3 characters | Customer's region. | |
City | No | 70 characters | Customer's city. | |
Zip | No | 25 characters | Customer's post zip code. | |
isConvert | No | 0 – don't convert to the base currency 1 - don't convert to the base currency if possible 2 – always convert to the base currency | 1 | Currency conversion indicator |
Format | No | 4 – SOAP | 5 | Results format. |
Signature | No | String | The string is joined according to determined rules. Then the MD5 hash prepared from this string. Hash is signed by private RSA key of the merchant. Key length - 1024. Received bit sequence is a signature. Signature is transferred BASE64 coded string. | |
Chequeitems | No/Yes** | String in JSON-format | Cheque items according to the section “Payment with cheque”. | |
GenerateReceipt | No | 0 or 1 | 1 | Permission to generate of a fiscal receipt. If the value of parameter is 0, the generation of a fiscal receipt is prohibited for this order. |
Tax | No | 10 characters | Parameter is determined by the “Default tax rate” option of the merchant and used in the mode without transfer of the cheque items (the entire amount must be paid with one rate). | |
ReceiptLine | No | 128 characters | Parameter is determined by the “Default text of cheque item” option of the merchant and used in the mode without transfer of the cheque items. | Text description of the cheque item, if the cheque has one single item. |
FPMode | No | Number | Parameter is determined by the “Default payment method” option of the merchant and used in the mode without transfer of the cheque items. | |
TaxationSystem | No/Yes* | Number | From the merchant’s or CRE settings |
Note to the parameter TokenType, the value of which should be equal to 5, and also the value of the PaymentToken parameter, which must contain the unique customer number in the merchant database (CustomerNumber) and the unique identifier of the saved customer card received during the initial operation of this customer from the IPS Assist.
The payment will be made as a CIT COF operation with the earlier saved card at the initial payment for this token of this customer.
The list of response parameters is similar to the standard response of the Token Pay service.
Payment will be made as a CIT COF operation only if the corresponding processing is set up for the merchant in the IPS Assist. Otherwise, the operation will fail.
If the merchant does not use the Token Pay payment web service and the information about the initial payment in the form of a token for CIT COF received from IPS Assist, then subsequent payments for the customer will be made according to the One Click program.
MIT COF operations
Subsequent operations can be initiated by the merchant. These operations are called «Merchant Initialized Transaction» (MIT).
Recurrent payments are used for the implementation of MIT COF operations in APC Assist.
Recurrent payments are used when periodic withdrawal of funds from a customer’s bank card to the account of the service provider’s company is required. This is a different kind of subscription - payment for hosting, mobile phone, access to resources, etc. This method is convenient for the user, since the card data is entered by the customer once during the first payment.
The merchant can store the subscription schedule on its side and initiate subsequent payments through a request to the web service of the IPS Assist (description of the parameters of the initiating authorization request and the web service for subsequent payments see the corresponding section.
In contrast to recurrent payments, the amounts of MIT COF payments, as well as the intervals at which they are made, are not fixed. Thus, the merchant can initiate a payment of the required amount at any time (for example, in the case of a zeroing of the balance of a service).
To make subsequent payments as MIT COF, only one of the additional parameters must be transferred:
Parameter | Mandatory field | Adopted values | Default value | Description |
RecurringIndicator | No | 1 –recurring payment 0 – standard payment | 0 | Recurring payment indicator |
The remaining parameters related to the restrictions on the amount of payment and the frequency of their execution are optional.
Payment will be made as a MIT COF operation only if the corresponding processing is set up for the merchant in the IPS Assist. Otherwise, the transaction will be carried out as a regular recurrent payment
In this case, the merchant must send the required additional parameters that determine the amounts and intervals for making subsequent payments)
Additional web services for COF
Getting a list of customer cards tokens
The web service allows to a merchant to receive a list of tokens of cards by the unique identifier of their client.
To access the web service send a request using the POST method to the request URL https://<SERVER_NAME>/pay/oneclick/v1/token.cfm with parameters in JSON format.
List of request parameters:
Parameter | Mandatory field | Adopted values | Default value | Description | |
Merchant | Merchant_ID | Yes | Number | The enterprise identifier in IPS Assist | |
Login | Yes | 20 characters | Web service user login | ||
Password | Yes | 30 characters | Web service user password | ||
CustomerNumber* | Yes | 32 characters | Merchant's internal customer identification | ||
Language | No | RU - Russian, EN - English | Language of legal entity/enterprise | Language of authorized pages | |
*The parameter is automatically validated according to the rules.
An example of request: