NAV Navbar
Example

General

Verison 3.0, date 15.03.2019

Terms and Definitions

Transaction Types

The system involves two types of operations: payment and refund. In the first case, money is transferred from holder's account to the merchant, in the second - vice versa. A merchant performs a refund if a buyer wants to return goods, and it is always associated with a payment transaction, which amount returns to a holder. It is possible to refund a whole payment amount or it's part only. Money usually comes back to a holder’s card the same day, but sometimes (it depends on an issuer) it can take up to 3 days. The payment operation, unlike the refund, can be cancelled. Payment can be canceled by a merchant if the payment has been made with an error: incorrect amount, technical failure on the merchant's side, etc. There is a limitation - operation can be cancelled only if a merchant using the two-stage payment scheme. Money at the same time will be available on the card almost immediately.

Payment Schemes

There are two options to make a payment transaction: single message scheme (SMS) and dual message scheme (DMS).

Single message payment is made by a single command, depending on the authorization results money is transferred to a merchant.

Dual message payment uses 2 commands: one is used for authorization and another — for a withdraw. After a successful authorization, transaction amount is going to be locked on a cardholder’s account and become unusable for other payments. Then merchant has up to 7 days (depending on a card type) to confirm a transaction to make a withdraw. If a transaction hasn't been confirmed during this time interval, it becomes cancelled automatically. It is possible to confirm full amount or it's part only.

As a rule, the dual message scheme is used to obtain a deposit from a payer, for example, in rental companies or hotels.

Depending on a configuration, the system can automatically confirm dual message payments within a specified number of days.

Payment Methods

A payment can be made using following methods:

3-D Secure

3-D Secure is a common name of Verified By Visa and MasterCard Secure Code programs from Visa and MasterCard's respectively. In general, such program shall authenticate a cardholder (that is to protect against an unauthorized card usage) by an issuer before a payment. Actually, it looks as follows: a cardholder specifies card data. Then the issuer’s web site opens, where a cardholder has to enter a password or a secret code (usually, the code is sent in a SMS message). If the code is correct, a payment will be successful. Otherwise, it will be rejected.
3ds-demo

During the payment process, 3-D Secure appears not on all cards, but only on those, Issuers supporting this technology. Certainly, payments without 3-D Secure are a less secure option.

Payment Widget

Payment widget is a pop-up form to enter card data and payer’s email address. The widget automatically defines a payment system type: Visa, MasterCard, Maestro or MIR, and an emitting bank of a card, corresponding logos are also shown. The form is optimized for use in any browsers and mobile devices. Within a widget an iframe opens, which guarantees a security of card data sent, and does not require a certification for merchant's usage.

Widget Installation

To install a widget, you need to add a script on a web site to head section:

<script src="https://widget.cloudpayments.ru/bundles/cloudpayments"></script>

To get this payment form displayed, register a function to call charge or auth methods:


this.pay = function () {
    var widget = new cp.CloudPayments();
    widget.charge({ // options
            publicId: 'test_api_00000000000000000000001',  //id of site (from back office)
            description: 'Payment example (no real withdrawal)', // purpose/justification/description
            amount: 10, 
            currency: 'RUB', 
            invoiceId: '1234567', // order number  (optional)
            accountId: 'user@example.com', //customer's/user's/payer's ID (optional)
            data: {
                myProp: 'myProp value' //arbitrary set of parameters
            }
            skin:"mini" //skin of the  widget
        },
        function (options) { // success
            //action upon successful payment
        },
        function (reason, options) { // fail
            //action upon unsuccessful payment
        });
};    

Specify a function call for an event, for example, a click on the «Pay» button:

$('#checkout').click(pay);

The widget's is presented in our demo store. For testing, you can use both test card data and real ones. Cash withdrawal will not occur.

Parameters

A call of the charge or auth function defines a payment scheme:

Parameter Type Use Description
publicId String Required A web site identifier; located in Back Office
description String Required Description of a payment purpose in any format
amount Float Required Payment amount
currency String Required Currency: RUB/USD/EUR/GBP (see the reference)
invoiceId String Optional Order or Invoice number
accountId String Required for creation of subscription Payer's ID (endpoint customer)
email String Optional E-mail of that user
requireEmail bool Optional Require user's email address to be specified in a widget
data Json Optional Any other data which will be related to a transaction, including instructions for a subscription creation or generation of an online receipt. We reserved names of following parameters and display their contents in the transaction registry, downloaded in the Back Office: name, firstName, middleName, lastName, nick, phone, address, comment, birthDate.
skin String Optional Widget design option. Possible values: "classic", "modern", "mini". "classic" - is default.

You can define the form behaviour for successful or unsuccessful payment using the following parameters:

Parameter Type Use Description
onSuccess Function or String Optional Either a function or a web site's page is specified. If a function is specified, it will be called after successful payment completion. If a page is specified, a payer will be directed to a specified page
onFail Function or String Optional Either a function or a web site's page is specified. If a function is specified, it will be called after unsuccessful payment completion. If a page is specified , a payer will be directed to a specified page.

Widget Localization

By default, the widget is displayed in Russian. To localize the widget for other languages add in widget initialization a language parameter.

var widget = new cp.CloudPayments({language: "en-US"});

List of supported languages:

languages Timezone Value
Russian MSK ru-RU
English CET en-US
Latvian CET lv
Azerbaijani AZT az
Russian ALMT kk
Kazakh ALMT kk-KZ
Ukrainian EET uk
Polish CET pl
Portuguese CET pt
Czech CET cs-CZ

Recurrent Payments (Subscription)

Once a payment is successful, the widget can automatically create a subscription to recurrent payments. For this you have to add some parameters:

Parameter Type Use Description
Interval String Required Interval. Possible values are: Day, Week, Month.
Period Int Required Period. Together with an interval, 1 Month means once a month, and 2 Week once two weeks.
MaxPeriods Int Optional Maximum number of payments in a subscription. No limitation by default
Amount Numeric Optional A regular payment amount. By default, matches with a first payment amount.
StartDate DateTime Optional Date and time of the first regular payment. By default, a startup will occur in a specified interval and the period, for example, in a month.
CustomerReceipt String Optional Data for generation of an online receipt.

Parameters to startup regular payments have to be added to the data.cloudPayments.recurrent object as shown below:

this.pay = function () {
    var widget = new cp.CloudPayments();
    var receipt = {
            Items: [//positions of goods
                 {
                    label: 'Product #2', //goods name
                    price: 300.00, //price (per 1 item)
                    quantity: 3.00, //quantity
                    amount: 900.00, // line amount (incl. the discounts)
                    vat: 20, // vat rate
                    method: 0, // tag-1214 sign of a calculation method
                    object: 0, // tag-1212 sign of  the subject of calculation - sign of items, goods, services, payment, payout or other subject of calculation
                }
            ],
            taxationSystem: 0, 
            email: 'user@example.com', //e-mail of customer, if you need to send an online-receipt
            phone: '', //phone of customer, if you need to send an online-receipt in SMS as link
            isBso: false, // receipt hasn't a strict reporting form
            amounts:
            {
                electronic: 900.00, // The amount of payment by electronic money (2 decimal places)
                advancePayment: 0.00, // Amount from prepayment (offset of advance payment) (2 decimal places)
                credit: 0.00, // Amount of prepayment (on credit) (2 decimal places)
                provision: 0.00 // The amount of payment by the reciprocal grant (certificates, other material values) (2 decimal places) 
            }
        };

    var data = {};
    data.cloudPayments = {recurrent: { interval: 'Month', period: 1, customerReceipt: receipt}}; // create a monthly subscription

    widget.charge({ // options
        publicId: 'test_api_00000000000000000000001', //id of site (from back office)
        description: 'Subscription on monthly access to https://example.com', //justification
        amount: 1000, //subscription amount
        currency: 'RUB', 
        invoiceId: '1234567', //order or invoice number (optional) 
        accountId: 'user@example.com', //customer/user's ID  (required for subscription)
        data: data
    },
    function (options) { // success
               //action upon successful payment
    },
    function (reason, options) { // fail
                //action upon unsuccessful payment
    });
};

For more examples of accepting payments using the widget, see Integration Scenarios.

To cancel recurrent payments, use BackOffice features, API or provide a buyer with a link to the system web site https://my.cloudpayments.ru/unsubscribe where he can find and cancel subscriptions himself.

Widget Mobile

A script automatically defines user device and starts the most suitable widget option: usual one or optimized for mobile devices. For buyer's convinience widget’s mobile version occupies a whole screen and prompts to make a payment using a card, or Apple Pay or Google Pay.

You can make payments in a widget via Apple Pay and Google Pay if following conditions are met:

  1. A web site runs HTTPS and supports TLS version 1.2.
  2. A web site provides no "mixed content", when a part of resources is loaded over HTTPS, and another part — over HTTP.
  3. For Apple Pay payments you must be registered in the Apple Developer program, to receive a certificate and to confirm you own a domain — see the guide.

Checkout Script

Checkout — is a script you need to add to your site. It collects card data from a specified form and uses them for cryptogram generation. Cryptogram is needed for making a payment via our API.

The cryptogram is generated by the RSA algorithm with a key length of 2048 bit and complies with a standard to protect card data. If following requirements are complied with, card data do not reach you, but your server still influences card data security.

Requirements

Form requirements:

Cryptogram requirements:

PCI DSS security requirements:

From the PCI DSS point of view, a similar integration method is classified as follows: “E-commerce merchants who outsource all payment processing to PCI DSS validated third parties, and who have a website(s) that doesn’t directly receive cardholder data but that can impact the security of the payment transaction. No electronic storage, processing, or transmission of any cardholder data on the merchant’s systems or premises.” Means the payment data are processed by a third party, but the web site influences a security of card data.

To comply with standard requirements, you have to fill a SAQ-EP self-estimation sheet and quarterly pass an ASV test.

For more information on compliance with PCI requirements, see PCI DSS.

Installation

To create a cryptogram, you have to add checkout script on a page with a payment form:

<script src="https://widget.cloudpayments.ru/bundles/checkout"></script>

Create a card data entering form:

<form id="paymentFormSample" autocomplete="off">
    <input type="text" data-cp="cardNumber">
    <input type="text" data-cp="expDateMonth">
    <input type="text" data-cp="expDateYear">
    <input type="text" data-cp="cvv">
    <input type="text" data-cp="name">
    <button type="submit">Pay 100 Rubles</button>
</form>

Input fields must be marked with following attributes:

Add a script to create a cryptogram:

this.createCryptogram = function () {
    var result = checkout.createCryptogramPacket();

    if (result.success) {
        // if cryptogram generated successfully
        alert(result.packet);
    }
    else {
        // if issues found, object  `result.messages` returns: 
        // { name: "Name field contains too much letters", cardNumber: "Wrong PAN" }
        // where `name`, `cardNumber` matches to attribute values `<input ... data-cp="cardNumber">`
       for (var msgName in result.messages) {
           alert(result.messages[msgName]);
       }
    }
};

$(function () {
    /* Creation of checkout */
    checkout = new cp.Checkout(
    // public id 
    "test_api_00000000000000000000001",
    // tag, containing card data fields
    document.getElementById("paymentFormSample"));
});

Send the cryptogram and a name of the card holder to the server and call a payment method via API.

You may learn how Checkout script works in our demo store . For testing, you can use both test card data and real ones. Cash withdrawal will not occur.

When developing your own form, pay attention to the following points:

Recurrent Payments

Recurrent payments, also known as payments by subscription - the ability to perform regular money withdrawal from a payer's bank card without re-entering of card details and without the participation of a payer to initiate the next payment.

Recurrent payments always begin with the first (setup) payment, for which a payer must enter the details of his card. Be sure to inform a cardholder for subsequent regular payments on time and get his consent to direct withdrawal.

There is a widespread belief that the task of recurrent payments is to set the amount to be withdrawn from the client’s card each month. The choice of a regular payment system is based only on the cost of the services provided. In reality, the situation is more complicated, because quality service requires many more functions and features, and therefore the procedure for launching and processing recurrent payments in CloudPayments is as simple and flexible as possible, while in other systems it is extremely complicated and limited.

Starting and Stopping Subscriptions

You can start recurrent payments at any time once made a setup payment: at the same time, in a week or a month. Only one restriction: the interval between regular payments, as well as between the starting and the first regular payment can not exceed one year.

Example: A buyer pays the first month of service once through the setup payment and agrees to a monthly withdrawal from his card starting by the second month. Running regular payments can be made through API or payment widget.

If the buyer refuses further payments, you can cancel the subscription at any time:

Also, a payer can independently find and cancel his regular payments at CloudPayments site.

Customizing the Payment Schedule

Withdrawal Period and Interval Selection

The system can make regular payments every 2 weeks, 1 time per month, every 3 months and so on: you can specify any period.

Withdrawal Starting Date Selection

Recurrent payments can be started immediately when you create a subscription, or with a delay.

Example: a payer subscribes to your service in the middle of the month, you create a plan for monthly recurring payments starting from the next month on the 15th day.

Payment Limit

You can specify the maximum number of payments in a subscription, or you can create a plan without any limits. In the first case, recurrent payments will be automatically stopped once all the payments in the schedule are done.

Example: a buyer purchases goods worth 12,000 rubles in installments for a year: pays 1,000 rubles in an installment payment and subscribes to a recurrent payment plan of 1,000 rubles monthly, but not more than 11 withdrawals.

Freeze the Subscription Plan

Subscription to regular payments can be suspended for any period from your personal account or using API.

Example: a buyer asks to suspend the provision of services for a couple of months, you shift the date of the next payment for the corresponding period.

Payment Amount Change

Setup Payment Amount

The amount of the first (Setup) payment can be arbitrary and differ from the amount of subsequent recurrent payments.

Example: a buyer signs up at your service, you ask him to make a setup payment for 1 ruble to check the card. Further, with the consent of the user, launch recurrent payments for any amount.

Recurrent Payments Amount Change

The amount of recurrent payments can be changed at any time during the action of the plan through Back Office or via API.

Example: you give to buyer a discount on the first two months of using the service, then increase the subscription amount.

Automatic error correction

Errors that occur when making recurrent payments can be separated on two categories: recoverable and non-recoverable.

The first category includes errors associated with insufficient funds on the payer's card, with temporary technical problems or unavailability of the card issuing bank. As a rule, these problems are recoverable over time or by the intervention of the cardholder.

Errors that cannot be recovered fall into the second category: the card has expired, the card has been lost, the license has been revoked from the issuing bank.

Depending on the category, the system handles recurrent payment errors and responds differently.

Cardholder Interaction

In case of decline due to insufficient funds on the card, the system informs a holder that the last payment has been failed, recommends to top up the card balance and informs that the next attempt to withdrawal will be made the next day.

Retry

The system repeats the attempt to charge the card for several days, if another payment fails due to recoverable error.

Card Data Update

The system offers through its form to enter new card data to continue recurrent payments. If a buyer agrees, the system makes a new setup payment for the details of the card received, adds the payment to the subscription and continues to make regular payments by the updated card

Payer Notification

An important function of recurring payments is timely informing the cardholder of the next payment date. Buyers tend to forgetfulness, so a warning about the impending withdrawal removes the effect of surprise and significantly reduces a lack of no money on the card. CloudPayments always reminds payers of the next payment date, displaying the amount, payment description and payee.

SDK for iOS

The application demonstrates work of CloudPayments SDK for the iOS platform. Download from GitHub.

By that you will learn how to get a card data, create a cryptogram, do a 3-D Secure authorization and make a payment on iPhone or iPad.

Mobile application scheme:

  1. In the application, you must obtain the card data: number, expiration date, holder's name and CVV;
  2. Create a cryptogram by the card data using the SDK;
  3. Send a cryptogram and all the for payment from a mobile device to your server;
  4. Make a payment via API call with your server.

mobile-schema

Terms of use:

SDK-iOS Requirements

Adding to the Project

To install, you need to make a repository clone:

git clone https://github.com/cloudpayments/CloudPayments_iOSCheckout.git

In the project folder, execute the command:

 pod install

Preparation

To start accepting payments through mobile applications, you will need:

These data can be obtained in your account: https://merchant.cloudpayments.ru/ once you have finished with onboarding process CloudPayments.

SDK-iOS Features

Boolean Card.isCardNumberValid(cardNumber)
String Card.cardType(toString: Card.cardType(fromCardNumber: cardNumber))
let card = Card()
String card.makeCryptogramPacket(cardNumber, andExpDate: expDate, andCVV: cvv, andMerchantPublicID: Constants.merchantPulicId)

ApplePay Integration

Detailed description of ApplePay features with CloudPayments is here.

How to add Apple Pay in mobile.

Important. When processing a successful response from Apple Pay, you need to transform the PKPayment object into a cryptogram for transferring it via API CloudPayments:

let cryptogram = PKPaymentConverter.convert(toString: payment)

Once it transformed successfully, the cryptogram can be used for payment.

Making a Payment

In the example merchantPulicId and merchantApiPass is a test Public ID and Secret API. You may find it in your Back Office.
1) In the application, you need to get a PKPayment object from Apple Pay and transform it into a cryptogram, or obtain card data and create a cryptogram based on them;
2) Send a cryptogram and all data for payment from a mobile device to your server;
3) Make a payment with your server using a payment by a cryptogram method.

SDK for Android

The application demonstrates work of CloudPayments SDK for the Android platform. Download from Github.

By that you will learn how to get a card data, create a cryptogram, do a 3-D Secure authorization and make a payment on iPhone or iPad.

Mobile application scheme:

  1. In the application, you must obtain the card data: number, expiration date, holder's name and CVV;
  2. Create a cryptogram by the card data using the SDK;
  3. Send a cryptogram and all the for payment from a mobile device to your server;
  4. Make a payment via API call with your server.

mobile-schema

Terms of use:

SDK-Android Requirements

Adding to the Project

Add the following dependency to the build.gradle file of your project:

implementation 'ru.cloudpayments.android:sdk:1.0.0'

Project Structure:

Preparation

To start accepting payments through mobile applications, you will need:

These data can be obtained in your account: https://merchant.cloudpayments.ru/ once you have finished with onboarding process CloudPayments.

SDK-Android Features

boolean CPCard.isValidNumber(String cardNumber);

boolean CPCard.isValidExpDate(String cardDate); // cardDate in MMYY format

CPCard card = new CPCard(String cardNumber, String cardDate, String cardCVC);
String card.getType();

CPCard card = new CPCard(String cardNumber, String cardDate, String cardCVC);
String card.cardCryptogram(String publicId);

ThreeDsDialogFragment.newInstance(transaction.getAcsUrl(),
                String transactionId,
                String paReq)
                .show(getSupportFragmentManager(), "3DS");

Example of Making a Payment

1) Create a Cryptogram

CPCard card = new CPCard(String cardNumber, String cardDate, String cardCVC);
String card.cardCryptogram(String publicId);

2)Make a Payment Request via API

Payment by cryptogram.

To bind a card ("one click" payment) use method of a payment by a token.

Token can be obtained by reply on making a payment with a cryptogram, or via Notifications.

3) Show 3DS form if it been requested by Issuer.

ThreeDsDialogFragment.newInstance(transaction.getAcsUrl(),
                String transactionId,
                String paReq)
                .show(getSupportFragmentManager(), "3DS");

To get 3DS authentication results, implement the ThreeDSDialogListener interface in the Activity which is created and displayed by ThreeDsDialogFragment

public class CheckoutActivity implements ThreeDSDialogListener {
...
  @Override
    public void onAuthorizationCompleted(String md, String paRes) {
        post3ds(md, paRes); // Successful authentication, complete the post3ds API request to complete the payment
    }

    @Override
    public void onAuthorizationFailed(String html) {
        showToast("AuthorizationFailed"); // Authentication failed, display an error
    }
}

Google Pay Integration

About Google Pay

Documentation

Integration example of Google Pay API by Google

Adding to the Project

Add the following dependency to the build.gradle file:

implementation 'com.google.android.gms:play-services-wallet:16.0.1'

Add meta information to the application manifest file:

<meta-data
            android:name="com.google.android.gms.wallet.api.enabled"
            android:value="true" />

Making a payment via Google Pay

Configure the parameters:

PaymentMethodTokenizationParameters  params =
        PaymentMethodTokenizationParameters.newBuilder()
                .setPaymentMethodTokenizationType(
                WalletConstants.PAYMENT_METHOD_TOKENIZATION_TYPE_PAYMENT_GATEWAY)
                .addParameter("gateway", "cloudpayments")
                .addParameter("gatewayMerchantId", "Ваш Public ID")
                .build();

Specify the type of payment through the gateway (WalletConstants.PAYMENT_METHOD_TOKENIZATION_TYPE_PAYMENT_GATEWAY) and add two parameters:

1) gateway: cloudpayments;

2) gatewayMerchantId: Your Public ID, you may get it from Back Office.

With these parameters, request a Google Pay token:

String tokenGP = paymentData.getPaymentMethodToken().getToken();

Using the Google Pay token as a cryptogram of card data, make the payment using the API methods specified earlier.

API

API - application program interface of CloudPayments to interact Merchant's system with.

Interaface works on api.cloudpayments.ru and supports functions for making a payment, canceling a payment, returning money, confirming payments made by a dual scheme mode, creating and canceling subscriptions for recurrent payments, and sending invoices by email.

Interface Basics

Selection of format of the parameters to transfer is determined on the client side and is controlled via the request header Content- Type .

System's reply have JSON format, which is as minimum includes two parameters: Success and Message:

{ "Success": false, "Message": "Invalid Amount value" }

Requests Authentication

To authenticate the request, use HTTP Basic Auth - send the login and password in the header of HTTP request. Public ID is used as login, API Secret is used as password. Both of these values can be obtained in your account.

API Idempotency

Idempotency - the ability of API to produce the same result as the primary without re-processing in case of duplicated requests. This means that you can send several requests to the system with the same identifier, and only one request will be processed. All the answers will be identical. By this way, protection against network errors is implemented, which lead to the creation of duplicate records and actions.

To enable idempotency, it is necessary in API request to send a header with the key X-Request-ID containing a unique identifier. Generation of the request identifier remains on your side - it can be a guid, a combination of the order number, date and amount, or any other value on your choice. Each new request that needs to be processed must include the new X-Request-ID value. The processed result is stored in the system for 1 hour. The system stores only successful query results.

Test Method

To test the interaction with the API, you can call this method.

Method URL:
https://api.cloudpayments.ru/test

Parameters:
none.

Response example:
Method returns a request status.

{"Success":true,"Message":"bd6353c3-0ed6-4a65-946f-083664bf8dbd"}

Payment by a Cryptogram

Method to make a payment by a cryptogram, generated by the Checkout script, Apple Pay or Google Pay.

Method URL's:
https://api.cloudpayments.ru/payments/cards/charge — for single message scheme payment
https://api.cloudpayments.ru/payments/cards/auth — for dual message scheme payment

Parameters:

Parameter Type Use Description
Amount Numeric Required Payment amount
Currency String Required Currency : RUB/USD/EUR/GBP (see the reference)
IpAddress String Required Payer's IP address
Name String Required for all, except of Apple Pay & Google Pay Cardholder name in latin
CardCryptogramPacket String Required Cryptogram
InvoiceId String Optional Invoice or order number
Description String Optional Payment description
AccountId String Optional Payer's ID
Email String Optional Payer's E-mail to send an online-receipt to
JsonData Json Optional Any other data that will be associated with the transaction, including the instructions for Subsctiption creation or generation of online-receipt. We reserved the names of the following parameters and display it in the registry of operations, which you may download in Back Office: name, firstName, middleName, lastName, nick, phone, address, comment, birthDate.

In response, the server returns JSON with three components:

Possible response options:

Payment by a cryptogram request example:

{
    "Amount":10,
    "Currency":"RUB",
    "InvoiceId":"1234567",
    "Description":"Order №1234567 in shop example.com",
    "AccountId":"user_x",
    "Name":"CARDHOLDER NAME",
    "CardCryptogramPacket":"01492500008719030128SMfLeYdKp5dSQVIiO5l6ZCJiPdel4uDjdFTTz1UnXY+3QaZcNOW8lmXg0H670MclS4lI+qLkujKF4pR5Ri+T/E04Ufq3t5ntMUVLuZ998DLm+OVHV7FxIGR7snckpg47A73v7/y88Q5dxxvVZtDVi0qCcJAiZrgKLyLCqypnMfhjsgCEPF6d4OMzkgNQiynZvKysI2q+xc9cL0+CMmQTUPytnxX52k9qLNZ55cnE8kuLvqSK+TOG7Fz03moGcVvbb9XTg1oTDL4pl9rgkG3XvvTJOwol3JDxL1i6x+VpaRxpLJg0Zd9/9xRJOBMGmwAxo8/xyvGuAj85sxLJL6fA=="
}

Response example: incorrect request:

{"Success":false,"Message":"Amount is required"}

Response example: 3-D Secure authentication is required

{
    "Model": {
        "TransactionId": 504,
        "PaReq": "eJxVUdtugkAQ/RXDe9mLgo0Z1nhpU9PQasWmPhLYAKksuEChfn13uVR9mGTO7MzZM2dg3qSn0Q+X\nRZIJxyAmNkZcBFmYiMgxDt7zw6MxZ+DFkvP1ngeV5AxcXhR+xEdJ6BhpEZnEYLBdfPAzg56JKSKT\nAhqgGpFB7IuSgR+cl5s3NqFTG2NAPYSUy82aETqeWPYUUAdB+ClnwSmrwtz/TbkoC0BtDYKsEqX8\nZfZkDGgAUMkTi8synyFU17V5N2nKCpBuAHRVs610VijCJgmZu17UXTxhFWP34l7evYPlegsHkO6A\n0C85o5hMsI3piNIZHc+IBaitg59qJYzgdrUOQK7/WNy+3FZAeSqV5cMqAwLe5JlQwpny8T8HdFW8\netFuBqUyahV+Hjf27vWCaSx22fe+KY6kXKZfJLK1x22TZkyUS8QiHaUGgDQN6s+H+tOq7O7kf8hd\nt30=",
        "AcsUrl": "https://test.paymentgate.ru/acs/auth/start.do"
    },
    "Success": false,
    "Message": null
}

Response example: Transaction rejected. ReasonCode field contains error code (see the reference):

{
    "Model": {
        "TransactionId": 504,
        "Amount": 10.00000,
        "Currency": "RUB",
        "CurrencyCode": 0,
        "PaymentAmount": 10.00000,
        "PaymentCurrency": "RUB",
        "PaymentCurrencyCode": 0,
        "InvoiceId": "1234567",
        "AccountId": "user_x",
        "Email": null,
        "Description": "Order №1234567 in shop example.com",
        "JsonData": null,
        "CreatedDate": "\/Date(1401718880000)\/",
        "CreatedDateIso":"2014-08-09T11:49:41", //all dates in  UTC format
        "TestMode": true,
        "IpAddress": "195.91.194.13",
        "IpCountry": "RU",
        "IpCity": "Ufa",
        "IpRegion": "Республика Башкортостан",
        "IpDistrict": "Приволжский федеральный округ",
        "IpLatitude": 54.7355,
        "IpLongitude": 55.991982,
        "CardFirstSix": "411111",
        "CardLastFour": "1111",
        "CardExpDate": "05/19",
        "CardType": "Visa",
        "CardTypeCode": 0,
        "Issuer": "Sberbank of Russia",
        "IssuerBankCountry": "RU",
        "Status": "Declined",
        "StatusCode": 5,
        "Reason": "InsufficientFunds", // reason of  rejection
        "ReasonCode": 5051, //rejection code
        "CardHolderMessage":"Not enough funds on the card", //message for a payer
        "Name": "CARDHOLDER NAME",
    },
    "Success": false,
    "Message": null
}

Response example: transaction accepted:

{
    "Model": {
        "TransactionId": 504,
        "Amount": 10.00000,
        "Currency": "RUB",
        "CurrencyCode": 0,
        "InvoiceId": "1234567",
        "AccountId": "user_x",
        "Email": null,
        "Description": "Оrder №1234567 in shop example.com",
        "JsonData": null,
        "CreatedDate": "\/Date(1401718880000)\/",
        "CreatedDateIso":"2014-08-09T11:49:41", //all the dates in UTC format
        "AuthDate": "\/Date(1401733880523)\/",
        "AuthDateIso":"2014-08-09T11:49:42",
        "ConfirmDate": "\/Date(1401733880523)\/",
        "ConfirmDateIso":"2014-08-09T11:49:42",
        "AuthCode": "123456",
        "TestMode": true,
        "IpAddress": "195.91.194.13",
        "IpCountry": "RU",
        "IpCity": "Ufa",
        "IpRegion": "Республика Башкортостан",
        "IpDistrict": "Приволжский федеральный округ",
        "IpLatitude": 54.7355,
        "IpLongitude": 55.991982,
        "CardFirstSix": "411111",
        "CardLastFour": "1111",
        "CardExpDate": "05/19",
        "CardType": "Visa",
        "CardTypeCode": 0,
        "Issuer": "Sberbank of Russia",
        "IssuerBankCountry": "RU",
        "Status": "Completed",
        "StatusCode": 3,
        "Reason": "Approved",
        "ReasonCode": 0,
        "CardHolderMessage":"ayment successfully completed", //message for a payer
        "Name": "CARDHOLDER NAME",
        "Token": "a4e67841-abb0-42de-a364-d1d8f9f4b3c0"
    },
    "Success": true,
    "Message": null
}

3-D Secure Processing

To complete 3-D Secure authentication , you need to send a payer to the address specified in the parameter AcsUrl of server's response with following parameters:

Form example:

<form name="downloadForm" action="AcsUrl" method="POST">
    <input type="hidden" name="PaReq" value="eJxVUdtugkAQ/RXDe9mLgo0Z1nhpU9PQasWmPhLYAKksuEChfn13uVR9mGTO7MzZM2dg3qSn0Q+X\nRZIJxyAmNkZcBFmYiMgxDt7zw6MxZ+DFkvP1ngeV5AxcXhR+xEdJ6BhpEZnEYLBdfPAzg56JKSKT\nAhqgGpFB7IuSgR+cl5s3NqFTG2NAPYSUy82aETqeWPYUUAdB+ClnwSmrwtz/TbkoC0BtDYKsEqX8\nZfZkDGgAUMkTi8synyFU17V5N2nKCpBuAHRVs610VijCJgmZu17UXTxhFWP34l7evYPlegsHkO6A\n0C85o5hMsI3piNIZHc+IBaitg59qJYzgdrUOQK7/WNy+3FZAeSqV5cMqAwLe5JlQwpny8T8HdFW8\netFuBqUyahV+Hjf27vWCaSx22fe+KY6kXKZfJLK1x22TZkyUS8QiHaUGgDQN6s+H+tOq7O7kf8hd\nt30=">
    <input type="hidden" name="MD" value="504">
    <input type="hidden" name="TermUrl" value="https://example.com/post3ds?order=1234567">
</form>
<script>
    window.onload = submitForm;
    function submitForm() { downloadForm.submit(); }
</script>


To complete the payment, use the following Post3ds method.

Method URL:
https://api.cloudpayments.ru/payments/cards/post3ds

Parameters:

Parameter Type Use Description
TransactionId Int Required MD parameter value
PaRes String Required PaRes value

In response to a correctly formed request, the server will return either information about successful transaction, or — declined.

Payment by a Token (Recurring)

Method to make a payment by a token received either with payment by cryptogram, or via Pay notification.

Method URL's:
https://api.cloudpayments.ru/payments/tokens/charge — for single message scheme payment. https://api.cloudpayments.ru/payments/tokens/auth — for dual message scheme payment.

Parameters:

Parameter Type Use Description
Amount Numeric Required Amount of payment
Currency String Required RUB/USD/EUR/GBP (see the reference)
AccountId String Required Payer's ID
Token String Required Card tokens issued by the system. You get it with the first successful payment
InvoiceId String Optional Order or invoice number
Description String Optional Payment description/purpose
IpAddress String Optional Payer's IP address
Email String Optional Payer's E-mail to send an online-receipt to
JsonData Json Optional Any other data that will be associated with the transaction, including the instructions for Subsctiption creation or generation of online-receipt. We reserved the names of the following parameters and display it in the registry of operations, which you may download in Back Office: name, firstName, middleName, lastName, nick, phone, address, comment, birthDate.

In response, the server returns JSON with three components:

Possible response options:

Payment by token request example:

{
    "Amount":10,
    "Currency":"RUB",
    "InvoiceId":"1234567",
    "Description":"Order №1234567 in shop example.com",
    "AccountId":"user_x",
    "Token":"a4e67841-abb0-42de-a364-d1d8f9f4b3c0"
}

Response example: incorrect request

{"Success":false,"Message":"Amount is required"}

Response example: transaction rejected. ReasonCode field contains an error code (see the reference):

{
    "Model": {
        "TransactionId": 504,
        "Amount": 10.00000,
        "Currency": "RUB",
        "CurrencyCode": 0,
        "InvoiceId": "1234567",
        "AccountId": "user_x",
        "Email": null,
        "Description": "Order №1234567 in shop example.com",
        "JsonData": null,
        "CreatedDate": "\/Date(1401718880000)\/",
        "CreatedDateIso":"2014-08-09T11:49:41", //all the dates in UTC format
        "TestMode": true,
        "IpAddress": "195.91.194.13",
        "IpCountry": "RU",
        "IpCity": "Ufa",
        "IpRegion": "Республика Башкортостан",
        "IpDistrict": "Приволжский федеральный округ",
        "IpLatitude": 54.7355,
        "IpLongitude": 55.991982,
        "CardFirstSix": "411111",
        "CardLastFour": "1111",
        "CardType": "Visa",
        "CardTypeCode": 0,
        "Issuer": "Sberbank of Russia",
        "IssuerBankCountry": "RU",
        "Status": "Declined",
        "StatusCode": 5,
        "Reason": "InsufficientFunds", //decline reason
        "ReasonCode": 5051,
        "CardHolderMessage":"Недостаточно средств на карте", //message for a payer
        "Name": "CARDHOLDER NAME",
    },
    "Success": false,
    "Message": null
}

Response example: transaction accepted

{
    "Model": {
        "TransactionId": 504,
        "Amount": 10.00000,
        "Currency": "RUB",
        "CurrencyCode": 0,
        "InvoiceId": "1234567",
        "AccountId": "user_x",
        "Email": null,
        "Description": "Order №1234567 in shop example.com",
        "JsonData": null,
        "CreatedDate": "\/Date(1401718880000)\/",
        "CreatedDateIso":"2014-08-09T11:49:41",  //all the dates in UTC format
        "AuthDate": "\/Date(1401733880523)\/",
        "AuthDateIso":"2014-08-09T11:49:42",
        "ConfirmDate": "\/Date(1401733880523)\/",
        "ConfirmDateIso":"2014-08-09T11:49:42",
        "AuthCode": "123456",
        "TestMode": true,
        "IpAddress": "195.91.194.13",
        "IpCountry": "RU",
        "IpCity": "Уфа",
        "IpRegion": "Республика Башкортостан",
        "IpDistrict": "Приволжский федеральный округ",
        "IpLatitude": 54.7355,
        "IpLongitude": 55.991982,
        "CardFirstSix": "411111",
        "CardLastFour": "1111",
        "CardType": "Visa",
        "CardTypeCode": 0,
        "Issuer": "Sberbank of Russia",
        "IssuerBankCountry": "RU",
        "Status": "Completed",
        "StatusCode": 3,
        "Reason": "Approved",
        "ReasonCode": 0,
        "CardHolderMessage":"Оплата успешно проведена", //message for a payer
        "Name": "CARDHOLDER NAME",
        "Token": "a4e67841-abb0-42de-a364-d1d8f9f4b3c0"
    },
    "Success": true,
    "Message": null
}

Payment Confirmation

For payments made by DMS scheme, you need to confirm a transaction. Confirmation can be done through Back office, or via call of this API method.

Method URL:
https://api.cloudpayments.ru/payments/confirm

Parameters:

Parameter Type Use Description
TransactionId Int Required Systems transaction number
Amount Numeric Required Amount to confirm in currency of the transaction
JsonData Json Optional Any other data that will be associated with the transaction, including the instructions for generation of online-receipt

Request example:

{"TransactionId":455,"Amount":65.98}

Response example:

{"Success":true,"Message":null}

Payment Cancellation

Cancellation of payment can be made through your Back Office or by calling the API method.

Method URL:
https://api.cloudpayments.ru/payments/void

Parameters:

Parameter Type Use Description
TransactionId Int Required Systems transaction number

Request example:

{"TransactionId":455}

Response example:

{"Success":true,"Message":null}

Refund

Refund can be made through your Back Office or by calling the API method.

Method URL:
https://api.cloudpayments.ru/payments/refund

Parameters:

Parameter Type Use Description
TransactionId Int Required Systems transaction number
Amount Numeric Required Refund amount in currency of transaction
JsonData Json Optional Any other data that will be associated with the transaction, including the instructions for generation of online-receipt

Request example:

{"TransactionId":455, "Amount": 100}

Response example:

{"Success":true,"Message":null}

Payout by a Cryptogram

Payment by a cryptogram can be made through a call to this API method.

Method URL:
https://api.cloudpayments.ru/payments/cards/topup

Parameters:

Parameter Type Use Description
Name String Required Cardholder Name in Latin
CardCryptogramPacket String Required Payment Cryptogram
Amount Numeric Required Payment Amount
AccountId String Required Payer's ID
Email String Optional Payer's E-mail to send an online-receipt to
JsonData Json Optional Any other data that will be associated with the transaction. We reserved the names of the following parameters and display it in the registry of operations, which you may download in Back Office: name, firstName, middleName, lastName, nick, phone, address, comment, birthDate
Currency String Required Currency
InvoiceId String Optional Order or invoice number
Description String Optional Payment description/purpose

Request example:

{
    "Name":"CARDHOLDER NAME",
    "CardCryptogramPacket":"01492500008719030128SMfLeYdKp5dSQVIiO5l6ZCJiPdel4uDjdFTTz1UnXY+3QaZcNOW8lmXg0H670MclS4lI+qLkujKF4pR5Ri+T/E04Ufq3t5ntMUVLuZ998DLm+OVHV7FxIGR7snckpg47A73v7/y88Q5dxxvVZtDVi0qCcJAiZrgKLyLCqypnMfhjsgCEPF6d4OMzkgNQiynZvKysI2q+xc9cL0+CMmQTUPytnxX52k9qLNZ55cnE8kuLvqSK+TOG7Fz03moGcVvbb9XTg1oTDL4pl9rgkG3XvvTJOwol3JDxL1i6x+VpaRxpLJg0Zd9/9xRJOBMGmwAxo8/xyvGuAj85sxLJL6fA==",
    "Amount":1,
    "AccountId":"user@example.com",
    "Currency":"RUB"
    "InvoiceId":"1234567"
}

Response example:

{
   "Model":{
      "PublicId":"pk_b9b86395c99782f0d16386d83e5d8",
      "TransactionId":100551,
      "Amount":1,
      "Currency":"RUB",
      "PaymentAmount":1,
      "PaymentCurrency":"RUB",
      "AccountId":"user@example.com",
      "Email":null,
      "Description":null,
      "JsonData":null,
      "CreatedDate":"/Date(1517943890884)/",
      "PayoutDate":"/Date(1517950800000)/",
      "PayoutDateIso":"2018-02-07T00:00:00",
      "PayoutAmount":1,
      "CreatedDateIso":"2018-02-06T19:04:50",
      "AuthDate":"/Date(1517943899268)/",
      "AuthDateIso":"2018-02-06T19:04:59",
      "ConfirmDate":"/Date(1517943899268)/",
      "ConfirmDateIso":"2018-02-06T19:04:59",
      "AuthCode":"031365",
      "TestMode":false,
      "Rrn":"568879820",
      "OriginalTransactionId":null,
      "IpAddress":"185.8.6.164",
      "IpCountry":"RU",
      "IpCity":"Москва",
      "IpRegion":null,
      "IpDistrict":"Москва",
      "IpLatitude":55.75222,
      "IpLongitude":37.61556,
      "CardFirstSix":"411111",
      "CardLastFour":"1111",
      "CardExpDate":"12/22",
      "CardType":"Visa",
      "CardTypeCode":0,
      "Status":"Completed",
      "StatusCode":3,
      "CultureName":"ru",
      "Reason":"Approved",
      "ReasonCode":0,
      "CardHolderMessage":"Оплата успешно проведена",
      "Type":2,
      "Refunded":false,
      "Name":"WQER",
      "SubscriptionId":null,
      "GatewayName":"Tinkoff Payout"
   },
   "InnerResult":null,
   "Success":true,
   "Message":null
}

Payout by a Token

Payout by a token can be done through a call of the following API method.

Method URL:
https://api.cloudpayments.ru/payments/token/topup

Parameters:

Parameter Type Use Description
Token String Required Card tokens issued by the system. You get it with the first successful payment
Amount Numeric Required Payment Amount
AccountId String Required Payer's ID
Currency String Required Currency
InvoiceId String Optional Order or invoice number

Request example:

{
    "Token":"a4e67841-abb0-42de-a364-d1d8f9f4b3c0",
    "Amount":1,
    "AccountId":"user@example.com",
    "Currency":"RUB"
}

Response example:

{
   "Model":{
      "PublicId":"pk_b9b86395c99782f0d16386d83e5d8",
      "TransactionId":100551,
      "Amount":1,
      "Currency":"RUB",
      "PaymentAmount":1,
      "PaymentCurrency":"RUB",
      "AccountId":"user@example.com",
      "Email":null,
      "Description":null,
      "JsonData":null,
      "CreatedDate":"/Date(1517943890884)/",
      "PayoutDate":"/Date(1517950800000)/",
      "PayoutDateIso":"2018-02-07T00:00:00",
      "PayoutAmount":1,
      "CreatedDateIso":"2018-02-06T19:04:50",
      "AuthDate":"/Date(1517943899268)/",
      "AuthDateIso":"2018-02-06T19:04:59",
      "ConfirmDate":"/Date(1517943899268)/",
      "ConfirmDateIso":"2018-02-06T19:04:59",
      "AuthCode":"031365",
      "TestMode":false,
      "Rrn":"568879820",
      "OriginalTransactionId":null,
      "IpAddress":"185.8.6.164",
      "IpCountry":"RU",
      "IpCity":"Москва",
      "IpRegion":null,
      "IpDistrict":"Москва",
      "IpLatitude":55.75222,
      "IpLongitude":37.61556,
      "CardFirstSix":"411111",
      "CardLastFour":"1111",
      "CardExpDate":"12/22",
      "CardType":"Visa",
      "CardTypeCode":0,
      "Status":"Completed",
      "StatusCode":3,
      "CultureName":"ru",
      "Reason":"Approved",
      "ReasonCode":0,
      "CardHolderMessage":"Оплата успешно проведена",
      "Type":2,
      "Refunded":false,
      "Name":"WQER",
      "SubscriptionId":null,
      "GatewayName":"Tinkoff Payout"
   },
   "InnerResult":null,
   "Success":true,
   "Message":null
}

Transaction Details

Method returns a transaction details.

Method URL:
https://api.cloudpayments.ru/payments/get

Parameters:

Parameter Type Use Description
TransactionId Int Required Transaction number

If a transaction is found, the system returns an information about it.

Request example:

{"TransactionId":504}

Response example:

{
    "Model": [{
        "TransactionId": 504,
        "Amount": 10.00000,
        "Currency": "RUB",
        "CurrencyCode": 0,
        "InvoiceId": "1234567",
        "AccountId": "user_x",
        "Email": null,
        "Description": "Order №1234567 in shop example.com",
        "JsonData": null,
        "CreatedDate": "\/Date(1401718880000)\/",
        "CreatedDateIso":"2014-08-09T11:49:41", //all the dates are in UTC format
        "AuthDate": "\/Date(1401733880523)\/",
        "AuthDateIso":"2014-08-09T11:49:42",
        "ConfirmDate": "\/Date(1401733880523)\/",
        "ConfirmDateIso":"2014-08-09T11:49:42",
        "PayoutDate": "\/Date(1401733880523)\/", 
        "PayoutDateIso":"2014-08-09T11:49:42",
        "PayoutAmount": 99.61, 
        "TestMode": true,
        "IpAddress": "195.91.194.13",
        "IpCountry": "RU",
        "IpCity": "Уфа",
        "IpRegion": "Республика Башкортостан",
        "IpDistrict": "Приволжский федеральный округ",
        "IpLatitude": 54.7355,
        "IpLongitude": 55.991982,
        "CardFirstSix": "411111",
        "CardLastFour": "1111",
        "CardExpDate": "05/19",
        "CardType": "Visa",
        "CardTypeCode": 0,
        "Issuer": "Sberbank of Russia",
        "IssuerBankCountry": "RU",
        "Status": "Completed",
        "StatusCode": 3,
        "Reason": "Approved",
        "ReasonCode": 0,
        "CardHolderMessage":"Оплата успешно проведена", //message for payer
        "Name": "CARDHOLDER NAME",
    }],
    "Success": true,
    "Message": null
}

Payment Status Check

Order search method. Returns it's status (see the reference).

Method URL:
https://api.cloudpayments.ru/payments/find

Parameters:

Parameter Type Use Description
InvoiceId String Required Order or invoice number

If the payment for the specified order number is found, the system will return either information about the successful transaction or about the declined If several payments with the specified order number are found, the system will return an information about the last operation only.

Request example:

{"InvoiceId":"123456789"}

Response example:

{"Success":false,"Message":"Not found"}

Transaction List

Method to get a list of transactions for the day.

Method URL:
https://api.cloudpayments.ru/payments/list

Parameters:

Parameter Type Use Description
Date Date Required Date to check
TimeZone String Optional Time zone code, UTC by default

All the transactions registered on the specified day will be returned in the list. For your convenience, you can specify the time zone code (see the reference)

Request example:

{"Date":"2019-02-21", "TimeZone": "MSK"}

Response example:

{
    "Model": [{
        "TransactionId": 504,
        "Amount": 10.00000,
        "Currency": "RUB",
        "CurrencyCode": 0,
        "InvoiceId": "1234567",
        "AccountId": "user_x",
        "Email": null,
        "Description": "Payment at example.com",
        "JsonData": null,
        "CreatedDate": "\/Date(1401718880000)\/",
        "CreatedDateIso":"2014-08-09T11:49:41", //all the dates are in chosen time zone
        "AuthDate": "\/Date(1401733880523)\/",
        "AuthDateIso":"2014-08-09T11:49:42",
        "ConfirmDate": "\/Date(1401733880523)\/",
        "ConfirmDateIso":"2014-08-09T11:49:42",
        "PayoutDate": "\/Date(1401733880523)\/", 
        "PayoutDateIso":"2014-08-09T11:49:42",
        "PayoutAmount": 99.61, 
        "TestMode": true,
        "IpAddress": "195.91.194.13",
        "IpCountry": "RU",
        "IpCity": "Уфа",
        "IpRegion": "Республика Башкортостан",
        "IpDistrict": "Приволжский федеральный округ",
        "IpLatitude": 54.7355,
        "IpLongitude": 55.991982,
        "CardFirstSix": "411111",
        "CardLastFour": "1111",
        "CardExpDate": "05/19",
        "CardType": "Visa",
        "CardTypeCode": 0,
        "Issuer": "Sberbank of Russia",
        "IssuerBankCountry": "RU",
        "Status": "Completed",
        "StatusCode": 3,
        "Reason": "Approved",
        "ReasonCode": 0,
        "CardHolderMessage":"Оплата успешно проведена", //message for payer
        "Name": "CARDHOLDER NAME",
    }],
    "Success": true,
}

Token List

Method of getting a list of all payment tokens.

Method URL:
https://api.cloudpayments.ru/payments/tokens/list

Parameters:
none.

Response example:

{
    "Model": [
        {
            "Token": "tk_020a924486aa4df254331afa33f2a",
            "AccountId": "user_x",
            "CardMask": "4242 42****** 4242",
            "ExpirationDateMonth": 12,
            "ExpirationDateYear": 2020
        },
        {
            "Token": "tk_1a9f2f10253a30a7c5692a3fc4c17",
            "AccountId": "user_x",
            "CardMask": "5555 55****** 4444",
            "ExpirationDateMonth": 12,
            "ExpirationDateYear": 2021
        },
        {
            "Token": "tk_b91062f0f2875909233ab66d0fc7b",
            "AccountId": "user_x",
            "CardMask": "4012 88****** 1881",
            "ExpirationDateMonth": 12,
            "ExpirationDateYear": 2022
        }
    ],
    "InnerResult": null,
    "Success": true,
    "Message": null
}

Creation of Subscriptions on Recurrent Payments

Method of creation of subscriptions on recurrent payments.

Method URL:
https://api.cloudpayments.ru/subscriptions/create

Parameters:

Parameter Type Use Description
Token String Required Card tokens issued by the system. You get it with the first successful payment
AccountId String Required Payer's ID
Description String Required Payment description/purpose
Email String Required Payer's E-mail
Amount Numeric Required Payment amount
Currency String Required Currency: RUB/USD/EUR/GBP (see the reference)
RequireConfirmation Bool Required If true — payments will work by DMS
StartDate DateTime Required Date time of the first subscription payment in UTC timezone
Interval String Required Possible values: Day, Week, Month
Period Int Required Works in combination with the Interval, 1 Month means once per mont, 2 Week — once per two weeks.
MaxPeriods Int Optional Maximum quantity of subscription payments.

In response to a correctly formed request, the system returns a message about the successful operation and the subscription identifier.

Request example:

{  
   "token":"477BBA133C182267FE5F086924ABDC5DB71F77BFC27F01F2843F2CDC69D89F05",
   "accountId":"user@example.com",
   "description":"Monthly subscription on some service at example.com",
   "email":"user@example.com",
   "amount":1.02,
   "currency":"RUB",
   "requireConfirmation":false,
   "startDate":"2014-08-06T16:46:29.5377246Z",
   "interval":"Month",
   "period":1
}

Response example:

{
   "Model":{
      "Id":"sc_8cf8a9338fb8ebf7202b08d09c938", //Subscription ID
      "AccountId":"user@example.com",
      "Description":"Monthly subscription on some service at example.com"
      "Email":"user@example.com",
      "Amount":1.02,
      "CurrencyCode":0,
      "Currency":"RUB",
      "RequireConfirmation":false, //true for enabling the DMS
      "StartDate":"\/Date(1407343589537)\/",
      "StartDateIso":"2014-08-09T11:49:41", //all the dates are in UTC
      "IntervalCode":1,
      "Interval":"Month",
      "Period":1,
      "MaxPeriods":null,
      "StatusCode":0,
      "Status":"Active",
      "SuccessfulTransactionsNumber":0,
      "FailedTransactionsNumber":0,
      "LastTransactionDate":null,
      "LastTransactionDateIso":null, 
      "NextTransactionDate":"\/Date(1407343589537)\/"
      "NextTransactionDateIso":"2014-08-09T11:49:41"
   },
   "Success":true
}

Subscription Details

Method of getting an information about the status of subscription.

Method URL:
https://api.cloudpayments.ru/subscriptions/get

Parameters:

Parameter Type Use Description
Id String Required Subscription ID

Request example:

{"Id":"sc_8cf8a9338fb8ebf7202b08d09c938"}

Response example:

{
   "Model":{
      "Id":"sc_8cf8a9338fb8ebf7202b08d09c938", //Subscription ID
      "AccountId":"user@example.com",
      "Description":"Monthly subscription on some service at example.com",
      "Email":"user@example.com",
      "Amount":1.02,
      "CurrencyCode":0,
      "Currency":"RUB",
      "RequireConfirmation":false, //true for enabling the DMS
      "StartDate":"\/Date(1407343589537)\/",
      "StartDateIso":"2014-08-09T11:49:41", //all the dates are in UTC
      "IntervalCode":1,
      "Interval":"Month",
      "Period":1,
      "MaxPeriods":null,
      "StatusCode":0,
      "Status":"Active",
      "SuccessfulTransactionsNumber":0,
      "FailedTransactionsNumber":0,
      "LastTransactionDate":null,
      "LastTransactionDateIso":null, 
      "NextTransactionDate":"\/Date(1407343589537)\/"
      "NextTransactionDateIso":"2014-08-09T11:49:41"
   },
   "Success":true
}

Method of getting a list of subscriptions for a particular account.

Method URL:
https://api.cloudpayments.ru/subscriptions/find

Parameters:

Parameter Type Use Description
accountId String Required Subscription ID

Request example:

{"accountId":"user@example.com"}

Response example:

{
  "Model": [
    {
      "Id": "sc_4bae8f5823bb8cdc966ccd1590a3b",
      "AccountId": "user@example.com",
      "Description": "Subscription on some service",
      "Email": "user@example.com",
      "Amount": 1.02,
      "CurrencyCode": 0,
      "Currency": "RUB",
      "RequireConfirmation": false,
      "StartDate": "/Date(1473665268000)/",
      "StartDateIso": "2016-09-12T15:27:48",
      "IntervalCode": 1,
      "Interval": "Month",
      "Period": 1,
      "MaxPeriods": null,
      "CultureName": "ru",
      "StatusCode": 0,
      "Status": "Active",
      "SuccessfulTransactionsNumber": 0,
      "FailedTransactionsNumber": 0,
      "LastTransactionDate": null,
      "LastTransactionDateIso": null,
      "NextTransactionDate": "/Date(1473665268000)/",
      "NextTransactionDateIso": "2016-09-12T15:27:48"
    },
    {
      "Id": "sc_b4bdedba0e2bdf279be2e0bab9c99",
      "AccountId": "user@example.com",
      "Description": "Subscription on some service #2",
      "Email": "user@example.com",
      "Amount": 3.04,
      "CurrencyCode": 0,
      "Currency": "RUB",
      "RequireConfirmation": false,
      "StartDate": "/Date(1473665268000)/",
      "StartDateIso": "2016-09-12T15:27:48",
      "IntervalCode": 0,
      "Interval": "Week",
      "Period": 2,
      "MaxPeriods": null,
      "CultureName": "ru",
      "StatusCode": 0,
      "Status": "Active",
      "SuccessfulTransactionsNumber": 0,
      "FailedTransactionsNumber": 0,
      "LastTransactionDate": null,
      "LastTransactionDateIso": null,
      "NextTransactionDate": "/Date(1473665268000)/",
      "NextTransactionDateIso": "2016-09-12T15:27:48"
    }
  ],
  "InnerResult": null,
  "Success": true,
  "Message": null
}

Recurrent Payments Subscription Change

Method of change the subscription on recurrent payments.

Method URL:
https://api.cloudpayments.ru/subscriptions/update

Parameters:

Parameter Type Use Description
Id String Required Subscription ID
Description String Optional Description of change
Amount Numeric Optional Amount to change to
Currency String Optional Currency: RUB/USD/EUR/GBP (see the reference)
RequireConfirmation Bool Optional If true — payments will work by DMS
StartDate DateTime Optional To change the date of first (or next following) payment in UTC zone.
Interval String Optional To change the interval. Possible values: Week, Month
Period Int Optional To change the period. In combination with the Interval, 1 Month means once per month, 2 Week — once per two weeks.
MaxPeriods Int Optional To change max periods of recurring payments

In response to a correct request, the system returns a message with the successful operation and subscription parameters.

Request example:

{  
   "Id":"sc_8cf8a9338fb8ebf7202b08d09c938",
   "description":"Rate №5",
   "amount":1200,
   "currency":"RUB"
}

Response example:

{
   "Model":{
      "Id":"sc_8cf8a9338fb8ebf7202b08d09c938", //Subscription ID
      "AccountId":"user@example.com",
      "Description":"Rate №5",
      "Email":"user@example.com",
      "Amount":1200,
      "CurrencyCode":0,
      "Currency":"RUB",
      "RequireConfirmation":false, //true for enabling the DMS
      "StartDate":"\/Date(1407343589537)\/",
      "StartDateIso":"2014-08-09T11:49:41", //all the dates are in UTC
      "IntervalCode":1,
      "Interval":"Month",
      "Period":1,
      "MaxPeriods":null,
      "StatusCode":0,
      "Status":"Active",
      "SuccessfulTransactionsNumber":0,
      "FailedTransactionsNumber":0,
      "LastTransactionDate":null,
      "LastTransactionDateIso":null, 
      "NextTransactionDate":"\/Date(1407343589537)\/"
      "NextTransactionDateIso":"2014-08-09T11:49:41"
   },
   "Success":true
}

Subscription on Recurrent Payments Cancellation

Method of cancellation of subscription on recurrent payments.

Method URL:

https://api.cloudpayments.ru/subscriptions/cancel

Parameters:

Parameter Type Use Description
Id String Required Subscription ID

In response to a correctly formed request, the system returns a message about the successful operation.

Request example:

{"Id":"sc_cc673fdc50b3577e60eee9081e440"}

Response example:

{"Success":true,"Message":null}

You can also provide a link to the system’s website — https://my.cloudpayments.ru/unsubscribe, where payer can independently find and cancel his/her regular payments.

Invoice Creation on Email

Method of link generation for taking payments through sending it to payer's email.

Method URL:
https://api.cloudpayments.ru/orders/create

Parameters:

Parameter Type Use Description
Amount Numeric Required Payment Amount
Currency String Required Currency: RUB/USD/EUR/GBP (see the reference)
Description String Required Payment description/purpose
Email String Optional Payer's E-mail
RequireConfirmation Bool Optional If true — payments will work by DMS
SendEmail Bool Optional If true — payer will get an email with the link on the invoice
InvoiceId String Optional Order or Invoice number
AccountId String Optional Payer's ID
OfferUri String Optional Link to the offer that will be shown on the order page
Phone String Optional Free format phone number of the payer
SendSms Bool Optional If true — payer will get a SMS with the link on the invoice
SendViber Bool Optional If true — payer will get a Viber message with the link on the invoice
CultureName String Optional Notifications language. Possible values: "ru-RU", "en-US"
SubscriptionBehavior String Optional For subscription creation. Possible values: CreateWeekly, CreateMonthly
JsonData Json Optional Any other data that will be associated with the transaction, including the instructions for generation of online-receipt

Request example:

{
    "Amount":10.0,
    "Currency":"RUB",
    "Description":"Payment at website example.com",
    "Email":"client@test.local",
    "RequireConfirmation":true,
    "SendEmail":false
}

Response example:

{
    "Model":{
        "Id":"f2K8LV6reGE9WBFn",
        "Number":61,
        "Amount":10.0,
        "Currency":"RUB",
        "CurrencyCode":0,
        "Email":"client@test.local",
        "Description":"Payment at website example.com",
        "RequireConfirmation":true,
        "Url":"https://orders.cloudpayments.ru/d/f2K8LV6reGE9WBFn",
    },
    "Success":true,
}

Created Invoice Cancellation

Method of created invoice cancellation.

Method URL:

https://api.cloudpayments.ru/orders/cancel

Parameters:

Parameter Type Use Description
Id String Required Invoice ID

In response to a correct request, the system returns a message about the successful operation.

Request example:

{"Id":"f2K8LV6reGE9WBFn"}

Response example:

{"Success":true,"Message":null}

View of Notification Settings

Method of view of notification settings (with selection of notification type).

Method URL:

https://api.cloudpayments.ru/site/notifications/{Type}/get

Parameters:

Parameter Type Use Description
Type String Required Notification type: Check/Pay/Fail and so on (see the reference)

Response example on Pay notification:
https://api.cloudpayments.ru/site/notifications/pay/get

{
    "Model": {
        "IsEnabled": true,
        "Address": "http://example.com",
        "HttpMethod": "GET",
        "Encoding": "UTF8",
        "Format": "CloudPayments"
    },
    "Success": true,
    "Message": null
}

Change of Notification Settings

Method of notification settings change.

Method URL:

https://api.cloudpayments.ru/site/notifications/{Type}/update

Parameters:

Parameter Type Use Description
Type String Required Notification type: Check/Pay/Fail and so on (see the reference)
IsEnabled Bool Optional True - enabled. Default — false.
Address String Optional, if IsEnabled=false, else Required Address for sending notifications (for HTTPS schemes, a valid SSL certificate is required).
HttpMethod String Optional HTTP method for sending notifications. Possible values: GET, POST. The default is GET.
Encoding String Optional Encoding of notifications. Possible values: UTF8, Windows1251. The default is UTF8.
Format String Optional The format of the notifications. Possible values: CloudPayments, QIWI, RT. The default is CloudPayments.

Example request for Pay notification:
https://api.cloudpayments.ru/site/notifications/pay/update:

{
    "IsEnabled": true,
    "Address": "http://example.com",
    "HttpMethod": "GET",
    "Encoding": "UTF8",
    "Format": "CloudPayments"
}

Response example:

{"Success":true,"Message":null}

Start of Apple Pay Session

Start of session is needed to take payments via Apple Pay in Web. Not needed for Mobile platforms.

Method URL:
https://api.cloudpayments.ru/applepay/startsession

Parameters:

Parameter Type Use Description
ValidationUrl String Required Address received in Apple JS

In response to a correct request, the system returns a session in the Model object for paying for Apple Pay in JSON format.

Request example:

{"ValidationUrl":"https://apple-pay-gateway.apple.com/paymentservices/startSession"}

Response example:

{
    "Model": {
        "epochTimestamp": 1545111111153,
        "expiresAt": 1545111111153,
        "merchantSessionIdentifier": "SSH6FE83F9B853E00F7BD17260001DCF910_0001B0D00068F71D5887F2726CFD997A28E0ED57ABDACDA64934730A24A31583",
        "nonce": "d6358e06",
        "merchantIdentifier": "41B8000198128F7CC4295E03092BE5E287738FD77EC3238789846AC8EF73FCD8",
        "domainName": "demo.cloudpayments.ru",
        "displayName": "demo.cloudpayments.ru",
        "signature": "308006092a864886f70d010702a0803080020101310f300d06096086480165030402010500308006092a864886f70d0107010000a080308203e230820388a00307650202082443f2a8069df577300a06082a8648ce3d040302307a312e302c06035504030c254170706c65204170706c69636174696f6e20496e746567726174696f6e204341202d20473331263024060355040b0c1d4170706c652043657274696669636174696f6e20417574686f7269747931133011060355040a0c0a4170706c6520496e632e310b3009060355040613025553301e170d3134303932353232303631315a170d3139303932343232303631315a305f3125302306035504030c1c6563632d736d702d62726f6b65722d7369676e5f5543342d50524f4431143012060355040b0c0b694f532053797374656d7331133011060355040a0c0a4170706c6520496e632e310b30090603550406130255533059301306072a8648ce3d020106082a8648ce3d03010703420004c21577edebd6c7b2218f68dd7090a1218dc7b0bd6f2c283d846095d94af4a5411b83420ed811f3407e83331f1c54c3f7eb3220d6bad5d4eff49289893e7c0f13a38202113082020d304506082b0601050507010104393037303506082b060105050730018629687474703a2f2f6f6373702e6170706c652e636f6d2f6f63737030342d6170706c6561696361333031301d0603551d0e041604149457db6fd57481868989762f7e578507e79b5824300c0603551d130101ff04023000301f0603551d2304183016801423f249c44f93e4ef27e6c4f6286c3fa2bbfd2e4b3082011d0603551d2004820114308201103082010c06092a864886f7636405013081fe3081c306082b060105050702023081b60c81b352656c69616e6365206f6e207468697320636572746966696361746520627920616e7920706172747920617373756d657320616363657074616e6365206f6620746865207468656e206170706c696361626c65207374616e64617264207465726d7320616e6420636f6e646974696f6e73206f66207573652c20636572746966696361746520706f6c69637920616e642063657274696669636174696f6e2070726163746963652073746174656d656e74732e303606082b06010505070201162a687474703a2f2f7777772e6170706c652e636f6d2f6365727469666963617465617574686f726974792f30340603551d1f042d302b3029a027a0258623687474703a2f2f63726c2e6170706c652e636f6d2f6170706c6561696361332e63726c300e0603551d0f0101ff040403020780300f06092a864886f76364061d04020500300a06082a8648ce3d04030203480030450220728a9f0f92a32ab999742bd55eb67340572a9687a1d62ef5359710f5163e96e902210091379c7d6ebe5b9974af40037f34c23ead98b5b4b7f70d355c86b2a81372f1b1308202ee30820275a0030201020208496d2fbf3a98da97300a06082a8648ce3d0403023067311b301906035504030c124170706c6520526f6f74204341202d20473331263024060355040b0c1d4170706c652043657274696669636174696f6e20417574686f7269747931133011060355040a0c0a4170706c6520496e632e310b3009060355040613025553301e170d3134303530363233343633305a170d3239303530363233343633305a307a312e302c06035504030c254170706c65204170706c69636174696f6e20496e746567726174696f6e204341202d20473331263024060355040b0c1d4170706c652043657274696669636174696f6e20417574686f7269747931133011060355040a0c0a4170706c6520496e632e310b30090603550406130255533059301306072a8648ce3d020106082a8648ce3d03010703420004f017118419d76485d51a5e25810776e880a2efde7bae4de08dfc4b93e13356d5665b35ae22d097760d224e7bba08fd7617ce88cb76bb6670bec8e82984ff5445a381f73081f4304606082b06010505070101043a3038303606082b06010505073001862a687474703a2f2f6f6373702e6170706c652e636f6d2f6f63737030342d6170706c65726f6f7463616733301d0603551d0e0416041423f249c44f93e4ef27e6c4f6286c3fa2bbfd2e4b300f0603551d130101ff040530030101ff301f0603551d23041830168014bbb0dea15833889aa48a99debebdebafdacb24ab30370603551d1f0430302e302ca02aa0288626687474703a2f2f63726c2e6170706c652e636f6d2f6170706c65726f6f74636167332e63726c300e0603551d0f0101ff0404030201063010060a2a864886f7636406020e04020500300a06082a8648ce3d040302036700306402303acf7283511699b186fb35c356ca62bff417edd90f754da28ebef19c815e42b789f898f79b599f98d5410d8f9de9c2fe0230322dd54421b0a305776c5df3383b9067fd177c2c216d964fc6726982126f54f87a7d1b99cb9b0989216106990f09921d00003182018d30820189020123458186307a312e302c06035504030c254170706c65204170706c69636174696f6e20496e746567726174696f6e204341202d20473331263024060355040b0c1d4170706c652043657274696669636174696f6e20417574686f7269747931133011060355040a0c0a4170706c6520496e632e310b300906035504061302555302082443f2a8069df577300d06096086480165030402010500a08195301806092a864886f70d010903310b06092a864886f70d010701301c06092a864886f70d010905310f170d3138313232303134323633395a302a06092a864886f70d010934311d301b300d06096086480165030402010500a10a06082a8648ce3d040302302f06092a864886f70d0109043122042066adfefd6fbe307934525c52b926dcf0734a2e8011a9c8558d7043d983960af3300a06082a8648ce3d04030204483046022100fc6436b2c9bde03c4691d2e3b0e23aca06e44ce0c05c7ff4fb34550f4079dd36022100d1c91be8ed57321fb1c7264f1a617311ed678609a75fed3be31cc0d5cea16cfe000000000000"
    },
    "Success": true,
    "Message": null
}

Localization

By default, the API issues messages for users in Russian. To get answers localized for other languages, pass in request parameters CultureName.

Supported languages:

Language TimeZone Code
Russian MSK ru-RU
English CET en-US
Latvian CET lv
Azerbaijani AZT az
Russian ALMT kk
Ukrainian EET uk
Polish CET pl

Airline Addendum

airline addendum — extended information about the itinerary receipt, which is transmitted with the transaction for processing to the payment system. Using an airline addendum allows you to reduce the risk of fraudulent transactions and lower the cost of processing a payment. It consists of information about the route receipt, information about segments (flights) and information about passengers.

Information on the itinerary receipt includes:

Parameter Type Use Description
BookingRef String Required, no ticket number is specified Booking number
TicketNumber String Required, if no reservation number is specified Ticket number

A segment means one flight: takeoff and landing. You must specify all segments of the route with the list of the following parameters:

Parameter Type Use Description
FlightNumber String Required Flight number
DepartureDateTime DateTime Required Departure date and time
ArrivalDateTime DateTime Required Arrival date and time
OriginatingCountry String Required Country of departure in Russian or English
OriginatingCity String Required Departure city in Russian or English
OriginatingAirportCode String(3) Required Departure airport code - 3 letters by IATA classification
DestinationCountry String Required Arrival country in Russian or English
DestinationCity String Required Arrival City in Russian or English
DestinationAirportCode String(3) Required Arrival airport code - 3 letters by IATA classification

For providing of information about passengers, it is necessary for each to specify the name and surname in Latin letters:

Parameter Type Use Description
FirstName String Required Passenger name
LastName String Required Passenger surname

AirlineAddendum can be submitted in parameter AirlineAddendum using any payment API method or via reply on check notification.

Example of airline addendum:

{
   "TicketNumber":"390 5241025377",
   "BookingRef":null,
   "Legs":[
      {
         "FlightNumber":"A3 971",
         "DepartureDateTime":"2014-05-26T05:15:00",
         "ArrivalDateTime":"2014-05-26T07:30:00",
         "OriginatingCountry":"Россия",
         "OriginatingCity":"Москва",
         "OriginatingAirportCode":"DME",
         "DestinationCountry":"Греция",
         "DestinationCity":"Афины",
         "DestinationAirportCode":"ATH"
      },
      {
         "FlightNumber":"A3 204",
         "DepartureDateTime":"2014-05-26T09:45:00",
         "ArrivalDateTime":"2014-05-26T10:50:00",
         "OriginatingCountry":"Греция",
         "OriginatingCity":"Афины",
         "OriginatingAirportCode":"ATH",
         "DestinationCountry":"Греция",
         "DestinationCity":"Родос",
         "DestinationAirportCode":"RHO"
      },
      {
         "FlightNumber":"A3 980",
         "DepartureDateTime":"2014-06-06T09:00:00",
         "ArrivalDateTime":"2014-06-06T13:45:00",
         "OriginatingCountry":"Греция",
         "OriginatingCity":"Родос",
         "OriginatingAirportCode":"RHO",
         "DestinationCountry":"Россия",
         "DestinationCity":"Москва",
         "DestinationAirportCode":"DME"
      }
   ],
   "Passengers":[
      {
         "FirstName":"KONSTANTIN",
         "LastName":"IVANOV"
      },
      {
         "FirstName":"JULIA",
         "LastName":"IVANOVA"
      }
   ]
}

Notifications

Notification - HTTP request from the system to your site. Similar requests are also called callback or webhook. The system provides several types of notifications: to check whether it is possible to make a payment, to inform about successful and unsuccessful payments, to notify about changes to subscriptions on recurrent payments, and also to inform about generated online-receipts.

Check

Performed once the cardholder has filled out the payment form and pressed the “Pay” button. It serves to payment validation on the website side: the system sends a request to the address of the merchant's website with payment information, and the website must validate and define if it's needed to confirm or reject the payment.

Parameters are in the body of request, listed below:

Parameter Format Use Description
TransactionId Numeric Required System's transaction number
Amount Numeric, dot as separator, two digits after dot Required Amount specified in the payment parameters
Currency String Required Currency: RUB/USD/EUR/GBP specified in the payment parameters (see reference)
DateTime yyyy-MM-dd HH:mm:ss Required Payment creation date / time in the UTC time zone
CardFirstSix String(6) Required First 6 digits of card number
CardLastFour String(4) Required Last 4 digits of card number
CardType String Required Card Payment System: Visa, MasterCard, Maestro or MIR
CardExpDate String Required Expiration date in format MM/YY
TestMode Bit (1 or 0) Required Test mode sign
Status String Required Payment status if successful: Completed — for SMS sheme, Authorized — for DMS scheme
OperationType String Required Transaction type: Payment/Refund/CardPayout (see reference)
InvoiceId String Optional Order number specified in the payment parameters
AccountId String Optional Payer's ID specified in the payment parameters
SubscriptionId String Optional Subscription identifier (for recurrent payments)
TokenRecipient String Optional Token for payouts
Name String Optional Cardholder's name
Email String Optional Payer's E-mail address
IpAddress String Optional Payer's IP address
IpCountry String(2) Optional Two-letter code of the country of the payer's location by ISO3166-1
IpCity String Optional Payer's location city
IpRegion String Optional Payer's location region
IpDistrict String Optional Payer's location district
Issuer String Optional Name of the card issuing bank
IssuerBankCountry String(2) Optional Two-letter country code of the card issuer by ISO3166-1
Description String Optional Payment description specified in the payment parameters
Data Json Optional An arbitrary set of parameters passed to the transaction

The system expects to receive a response in JSON format with the required parameter code:

{"code":0}

The code defines a payment result and can take the following values:

Code Description Result
0 Payment can be done The system will authorize the payment
10 Invalid order number Payment will be declined
11 Invalid amount Payment will be declined
13 Payment cannot be accepted Payment will be declined
20 Payment overdue Payment will be declined, the payer will receive a notification

Pay

Performed once the payment has been successfully completed - the issuer's authorization is received.

It serves to inform about the payment: the system sends a request to the address of the merchant with payment information, and merchant's site must register the fact of payment.

Parameters are in the body of request, listed below:

Parameter Format Use Description
TransactionId Numeric Required System's transaction number
Amount Numeric, dot as separator, two digits after dot Required Amount specified in the payment parameters
Currency String Required Currency: RUB/USD/EUR/GBP specified in the payment parameters (see reference)
DateTime yyyy-MM-dd HH:mm:ss Required Payment creation date / time in the UTC time zone
CardFirstSix String(6) Required First 6 digits of card number
CardLastFour String(4) Required Last 4 digits of card number
CardType String Required Card Payment System: Visa, MasterCard, Maestro or MIR
CardExpDate String Required Expiration date in format MM/YY
TestMode Bit (1 or 0) Required Test mode sign
Status String Required Payment status once authorized: Completed — for SMS sheme, Authorized — for DMS scheme
OperationType String Required Operation type: Payment/Refund/CardPayout (see reference)
GatewayName String Required Acquiring Bank Identifier
InvoiceId String Optional Order or Invoice number specified in the payment parameters
AccountId String Optional Payer's ID specified in the payment parameters
SubscriptionId String Optional Subscription identifier (for recurrent payments)
Name String Optional Cardholder's name
Email String Optional Payer's E-mail address
IpAddress String Optional Payer's IP address
IpCountry String(2) Optional The Two-letter code of the country of the payer's location by ISO3166-1
IpCity String Optional Payer's location city
IpRegion String Optional Payer's location region
IpDistrict String Optional Payer's location district
Issuer String Optional Name of the card issuing bank
IssuerBankCountry String(2) Optional Two-letter country code of the card issuer by ISO3166-1
Description String Optional Payment description specified in the payment parameters
Data Json Optional An arbitrary set of parameters passed to the transaction
Token String Optional Token of card for further payments without entering of card data
TotalFee Decimal Required Total fee value

The system expects to receive a response in JSON format with the required parameter code:

{"code":0}

The code defines the result of notification processing by the merchant and can take only one value:

Code Value
0 Payment registered

Fail

Performed if the payment has been declined and used to analyze the number and causes of failures.

Keep in mind that the fact of decline is not final - user can pay the second time.

Parameters are in the body of request, listed below:

Parameter Format Use Description
TransactionId Numeric Required System's transaction number
Amount Numeric, dot as separator, two digits after dot Required Amount specified in the payment parameters
Currency String Required Currency: RUB/USD/EUR/GBP specified in the payment parameters (see reference)
DateTime yyyy-MM-dd HH:mm:ss Required Payment creation date / time in the UTC time zone
CardFirstSix String(6) Required First 6 digits of card number
CardLastFour String(4) Required Last 4 digits of card number
CardType String Required Card Payment System: Visa, MasterCard, Maestro or MIR
CardExpDate String Required Expiration date in format MM/YY
TestMode Bit (1 or 0) Required Test mode sign
Reason String Required Decline reason
ReasonCode Int Required Error Code (see reference)
OperationType String Required Operation type: Payment/Refund/CardPayout (see reference)
InvoiceId String Optional Order or Invoice number specified in the payment parameters
AccountId String Optional Payer's ID specified in the payment parameters
SubscriptionId String Optional Subscription identifier (for recurrent payments)
Name String Optional Cardholder's name
Email String Optional Payer's E-mail address
IpAddress String Optional Payer's IP address
IpCountry String(2) Optional The Two-letter code of the country of the payer's location by ISO3166-1
IpCity String Optional Payer's location city
IpRegion String Optional Payer's location region
IpDistrict String Optional Payer's location district
Issuer String Optional Name of the card issuing bank
IssuerBankCountry String(2) Optional Two-letter country code of the card issuer by ISO3166-1
Description String Optional Payment description specified in the payment parameters
Data Json Optional An arbitrary set of parameters passed to the transaction

The system expects to receive a response in JSON format with the required parameter code:

{"code":0}

The code defines the result of notification processing by the merchant and can take only one value:

Code Value
0 A try registered

Confirm

Performed by DMS scheme once payment have been confirmed.

Parameters are in the body of request, listed below:

Parameter Format Use Description
TransactionId Numeric Required System's transaction number
Amount Numeric, dot as separator, two digits after dot Required Amount specified in the payment parameters
Currency String Required Currency: RUB/USD/EUR/GBP specified in the payment parameters (see reference)
DateTime yyyy-MM-dd HH:mm:ss Required Payment creation date / time in the UTC time zone
CardFirstSix String(6) Required First 6 digits of card number
CardLastFour String(4) Required Last 4 digits of card number
CardType String Required Card Payment System: Visa, MasterCard, Maestro or MIR
CardExpDate String Required Expiration date in format MM/YY
TestMode Bit (1 or 0) Required Test mode sign
Status String Required Payment status once authorized: Completed
InvoiceId String Optional Order or Invoice number specified in the payment parameters
AccountId String Optional Payer's ID specified in the payment parameters
SubscriptionId String Optional Subscription identifier (for recurrent payments)
Name String Optional Cardholder's name
Email String Optional Payer's E-mail address
IpAddress String Optional Payer's IP address
IpCountry String(2) Optional The Two-letter code of the country of the payer's location by ISO3166-1
IpCity String Optional Payer's location city
IpRegion String Optional Payer's location region
IpDistrict String Optional Payer's location district
Issuer String Optional Name of the card issuing bank
IssuerBankCountry String(2) Optional Two-letter country code of the card issuer by ISO3166-1
Description String Optional Payment description specified in the payment parameters
Data Json Optional An arbitrary set of parameters passed to the transaction
Token String Optional Token of card for further payments without entering of card data

The system expects to receive a response in JSON format with the required parameter code:

{"code":0}

The code defines the result of notification processing by the merchant and can take only one value:

Code Value
0 Payment registered

Refund

Performed if the payment has been refunded (fully or partially) on your initiative via the API or Back Office.

Parameters are in the body of request, listed below:

Parameter Format Use Description
TransactionId Numeric Required System's refund transaction number
PaymentTransactionId Int Required System's payment transaction number (original)
Amount Numeric, dot as separator, two digits after dot Required Refund amount in payment currency
DateTime yyyy-MM-dd HH:mm:ss Required Refund date / time in UTC time zone
OperationType String Required Operation type: Payment/Refund/CardPayout (see reference)
InvoiceId String Optional Invoice or Order number of the original transaction
AccountId String Optional Payer's ID of the original transaction
Email String Optional Payer's E-mail address
Data Json Optional An arbitrary set of parameters passed to the transaction

The system expects to receive a response in JSON format with the required parameter code:

{"code":0}

The code defines the result of notification processing by the merchant and can take only one value:

Code Value
0 Refund registered

Recurrent

Performed if the recurring payment subscription status has been changed.

Parameters are in the body of request, listed below:

Parameter Format Use Description
Id Int Required Subscription identifier
AccountId String Required Payer's ID
Description String Required Paymet Description
Email String Required Payer's E-mail address
Amount Numeric Required Payment amount
Currency String Required Currency: RUB/USD/EUR/GBP specified in the payment parameters (see reference)
RequireConfirmation Bool Required If true — payment will be made by DMS scheme
StartDate DateTime Required Date and time of the first payment according to the plan in the UTC time zone
Interval String Required Interval. Possible values: Week, Month
Period Int Required Period. In combination with the interval - 1 Month means once a month, 2 Week - once every two weeks.
Status String Required Subscription statuses
SuccessfulTransactionsNumber Int Required Number of successful payments
FailedTransactionsNumber Int Required Number of unsuccessful payments (reset after each successful)
MaxPeriods Int Optional Maximum number of payments per subscription
LastTransactionDate yyyy-MM-dd HH:mm:ss Optional Date and time of the last successful payment in the UTC time zone
NextTransactionDate yyyy-MM-dd HH:mm:ss Optional Date and time of the next payment in the UTC time zone

The system expects to receive a response in JSON format with the required parameter code:

{"code":0}

The code defines the result of notification processing by the merchant and can take only one value:

Code Value
0 Refund registered

Receipt

Performed once online receipt has been generated and sent to payer.

Used to inform about the generated online receipt: the system sends a request to the address of the merchant with the receipt details, and the merchant site have to register the information.

Parameters are in the body of request, listed below:

Parameter Format Use Description
Id String Required Receipt unique identifier
DocumentNumber Numeric Required Receipt number
SessionNumber Numeric Required Shift number
Number Numeric Required Receipt number in the shift
FiscalSign String Required Fiscal sign of the document
DeviceNumber Numeric Required Serial number of the cash register
RegNumber String Required Registration number of the cash register
FiscalNumber String Required Fiscal storage number
Inn Number Required TIN
Type String Required Accounting operation type see reference
Ofd String Required Fiscal data operator name
Url String Required URL address of receipt
QrCodeUrl String Required URL address with a QR code for checking a receipt in the Federal Tax Authority
TransactionId Numeric Optional System's transaction number
Amount Number Required Receipt amount
DateTime yyyy-MM-dd HH:mm:ss Required Date/time of receipt generation time in the UTC time zone
InvoiceId String Optional Order or Invoice number
AccountId String Optional Payer's ID
Receipt JSON Required Receipt composition
CalculationPlace String Optional Calculation Place
CashierName String Optional Cashier Name
SettlePlace String Optional Cash Register settle place

The system expects to receive a response in JSON format with the required parameter code:

{"code":0}

The code defines the result of notification processing by the merchant and can take only one value:

Code Value
0 Receipt registered

Cancel

Performed by DMS scheme once payment have been canceled via API or through Back Office.

Parameters are in the body of request, listed below:

Parameter Format Use Description
TransactionId Numeric Required System's canceled transaction number
Amount Numeric, dot as separator, two digits after dot Required Canceled transaction amount in the payment currency
DateTime yyyy-MM-dd HH:mm:ss Required Cancellation date / time in the UTC time zone
InvoiceId String Optional Order number of the operation
AccountId String Optional Payer's ID of the canceled operation
Email String Optional Payer's E-mail address
Data Json Optional An arbitrary set of parameters passed to the transaction

The system expects to receive a response in JSON format with the required parameter code:

{"code":0}

The code defines the result of notification processing by the merchant and can take only one value:

Code Value
0 Refund registered

Kkt

Performed once the online cash register switched to fiscal mode and contains the data of the registration report. Using this notification makes sense if you have dozens or hundreds of cash registers. For other cases, it is easier to obtain the necessary information through Back Office.

Parameters are in the body of request, listed below:

Parameter Format Use Description
Inn String Required TIN of the organization or individual entrepreneur
DeviceNumber String Required Cash register serial number
FiscalNumber String Required Fiscal storage number
RegNumber String Required Registration number of online-cash register
Status String Required Current status: Fiscalized
DocumentNumber String Required Fiscal document number
FiscalSign String Required Fiscal sign of the document
Date Date/Time Required Date and time of registration in format yyyy-MM-dd HH:mm:ss

The system expects to receive a response in JSON format with the required parameter code:

{"code":0}

The code defines the result of notification processing by the merchant and can take only one value:

Code Value
0 Status registered

Notification Validation

All the notifications — check, pay, fail, confirm, refund, recurrent, receipt and kkt have a HTTP header Content-HMAC which contains a validation value of the request, calculated using the algorithm HMAC. If you need to verify the authenticity and integrity of notifications, you can calculate the validation value on your side and compare it with what came in the request. The match confirms that the notice was sent from us and came to you in its original form.

When implementing notification validation, pay attention to the following points:

HMAC calculation Examples in different programming languages.

The system sends notifications from following addresses: 130.193.70.192 and 185.98.85.109.


Apple Pay

image1

Apple Pay is a modern, convenient and secure payment method from Apple. A payer binds the card to the phone once, and then, when paying, only confirms a payment with a fingerprint. The technology works in mobile applications and the Safari browser on the iPhone, iPad, Apple Watch and the latest MacBooks.

Apple Pay works with Visa and MasterCard cards and is available to all organizations and individual entrepreneurs working with CloudPayments without additional agreements and without changes in agreement conditions.

You can test payment via Apple Pay in our Demo Store (it's on Russian). Use either test or real card data. Money withdrawal will not occur.

Classic Integration

Apple Pay Merchant ID, certificates and domains

To use Apple Pay technology, you need to register a Merchant ID, generate a payment certificate, a certificate for web payments, and validate that you own the domains of the sites on which payment will be made.

Merchant ID registration:

  1. Sign in to console Apple Developer Account, to the section «Certificates, IDs & Profiles», then «Merchant IDs». Register new Merchant ID:

    • In the Description field, enter a description;
    • In the Identifier field, specify the address of your main site in the reverse order and with the prefix “merchant”. For example, if the address of your main site is shop.domain.ru, then Identitfier - merchant.ru.domain.shop.
  2. Save the result.

Certificates creation:

  1. Send an email tо support@cloudpayments.ru with your registered Apple Merchant ID. Our support team will generate two requests for certificates and send it back. The process takes no more than 10 minutes, but depending on the workload, it can be delayed.

  2. In Apple Developer console generate two cetificates: Payment Processing Certificate and Merchant Identity Certificate. Send both to our support.

Domain validation:

  1. Add the domain names in Apple Developer console For each site where you plan to accept payments through Apple Pay. Please note that sites must use the HTTPS scheme and support the protocol*TLS 1.2*.

  2. Confirm domain ownership.

In widget it will be possible to pay via Apple Pay.

Taking payments with Apple Pay

The payment scheme includes 3 stages:

Apple Pay in Mobile Applications

Use Apple's PassKit SDK to get a PaymentToken and the cryptogram payment method in the CloudPayments API for making a payment.

image4-2

Manual placement of Apple Pay on the site

If you want to place an Apple Pay button directly on your website, following the example below (not through the payment widget), then follow the further instructions.

Integration involves the use of the client part (javascript) and server. On the client, you check the compatibility of the device and process the events: session creation, payment authorization, payment processing.

On the server side, you need to make API calls:

  1. Apple Pay session start;

  2. Payment by a cryptogram.

Js-code example:


if (window.ApplePaySession) { //device check
    var merchantIdentifier = 'Ваш Apple Merchant ID';
    var promise = ApplePaySession.canMakePaymentsWithActiveCard(merchantIdentifier);
    promise.then(function (canMakePayments) {
        if (canMakePayments) {
            $('#apple-pay').show(); // Apple Pay button
        }
    });
}
$('#apple-pay').click(function () { //button handler
    var request = {
        // requiredShippingContactFields: ['email'], uncomment if you need an e-mail. You can also request postalAddress, phone, name. 
        countryCode: 'RU',
        currencyCode: 'RUB',
        supportedNetworks: ['visa', 'masterCard'],
        merchantCapabilities: ['supports3DS'],
        //specify the description of payment only in Latin!
        total: { label: 'Test', amount: '1.00' }, //payment description and amount
    }
    var session = new ApplePaySession(1, request);

    // event handler to create merchant session.
    session.onvalidatemerchant = function (event) {

        var data = {
            validationUrl: event.validationURL
        };

        // send a request to your server, and then request the CloudPayments API
        // for session start
        $.post("/ApplePay/StartSession", data).then(function (result) {
            session.completeMerchantValidation(result.Model);
        });
    };

    // payment authorization event handler
    session.onpaymentauthorized = function (event) {

        //var email = event.payment.shippingContact.emailAddress; //if the e-mail address was requested
        //var phone = event.payment.shippingContact.phoneNumber; //if the phone was requested
        //see all the options at https://developer.apple.com/reference/applepayjs/paymentcontact

        var data = {
            cryptogram: JSON.stringify(event.payment.token)
        };

        //send a request to your server, and then request the CloudPayments API
        //to make a payment
        $.post("/ApplePay/Pay", data).then(function (result) {
            var status;
            if (result.Success) {
                status = ApplePaySession.STATUS_SUCCESS;
            } else {
                status = ApplePaySession.STATUS_FAILURE;
            }

            session.completePayment(status);
        });
    };

    //Apple Pay session start
    session.begin();
});

Simplified Integration (Web Only)

We have simplified the registration procedure at Apple. For websites, creating an account in the Apple Developer console using our payment solutions is no longer necessary.
Now enough in Back Office in the site configuration:

To successfully enable the option your site must have HTTPS and support TLS 1.2.

image4

If you use Checkout script, you ned to place ApplePay manually.
In case of using the Widget possibility to make a payment by Apple Pay will appear automatically once the Apple Pay option has been enabled in Back Office.

Apple Pay Terms of Use

You can use Apple Pay technology with CloudPayments on websites and in mobile applications, subject to Apple’s terms of use:

image4-1

Google Pay

image-1-1

Google Pay is a fast and easy payment method in mobile apps and the Chrome browser on all Android devices. Google Pay provides all the convenience of payment and keeps customer data safe.

Google Pay works with Visa and MasterCard cards and is available to all organizations and individual entrepreneurs working with CloudPayments system without additional agreements.

You can test payment via Google Pay in our Demo Store (it's on Russian). Use either test or real card data. Money withdrawal will not occur.

Google Pay Basics

Google Pay combines the ability to pay through the Google Pay application (previously Android Pay) in stores and a regular payment card stored in a Google user account.

If a buyer makes a payment in the app or on the site from a mobile device that supports Google Pay, he will be asked to confirm the payment in a way that depends on the capabilities of the device.

When paying with devices without the Pay Google Apps, the buyer will be asked to select a saved card from his Google account and, at the discretion of the processor to pass 3-d Secure authentication.

Taking Payments with Google Pay

The payment scheme includes 3 stages:

Integration

Registration of sites and applications

To receive payments in an application or on a website with direct integration:

  1. Check that all requirements for branding have been met;
  2. Fill out the registration form, and then you will be contacted by a Google representative and instruct on further steps;
  3. Be prepared to send the build of the application (.apk) for verification or a link to the site with a payment page.

For taking payments through the widget using Gpay:

Google Pay in Mobile

Use Google Pay API for getting PaymentData and payment by a cryptogram method.

When making a request for payment data, specify the type of payment through the gateway: Wallet-Constants.PAYMENT_METHOD_TOKENIZATION_TYPE_PAYMENT_GATEWAY and add two parameters:

  1. gateway: cloudpayments;
  2. gatewayMerchantId: Public ID taken in CloudPayments Back Office.`
PaymentMethodTokenizationParameters params =
        PaymentMethodTokenizationParameters.newBuilder()
            .setPaymentMethodTokenizationType(
                WalletConstants.PAYMENT_METHOD_TOKENIZATION_TYPE_PAYMENT_GATEWAY)
            .addParameter("gateway", "cloudpayments")
            .addParameter("gatewayMerchantId", "your Public ID")
            .build();

See also:

Google Pay in Web

There are two options for accepting Google Pay payments on your website: using the built-in features of the widget or direct integration - placing a button directly on your page without additional forms. In the first case, no additional integration is required. In the second, your website should work using the HTTPS scheme and support the TLS protocol version 1.2. The domain of the site must be previously registered and validated by Google.

Direct integration involves the use of the client part (javascript) and server. On the client, you check the compatibility of the device and receive payment information, and on the server send a payment request to the API.

Js code example:


var allowedPaymentMethods = ['CARD', 'TOKENIZED_CARD'];
var allowedCardNetworks = ['MASTERCARD', 'VISA']; 
var tokenizationParameters = {
    tokenizationType: 'PAYMENT_GATEWAY',
    parameters: {
        'gateway': 'cloudpayments',
        'gatewayMerchantId': 'pk_b9fa79f3d759c56a9b856d8ac59b1' //your public id
    }
}
function getGooglePaymentsClient() {
    return (new google.payments.api.PaymentsClient({ environment: 'PRODUCTION' }));
}

// Google Pay API handler
function onGooglePayLoaded() {
    var paymentsClient = getGooglePaymentsClient();
    //device check
    paymentsClient.isReadyToPay({ allowedPaymentMethods: allowedPaymentMethods })
        .then(function (response) {
            if (response.result) {
                $('#gpay-checkout').show(); //button enable
                $('#gpay-checkout').click(onGooglePaymentButtonClicked);
            }
        });
}

//settings
function getGooglePaymentDataConfiguration() {
    return {
        merchantId: '04349806409183181471', //issued after registering with Google
        paymentMethodTokenizationParameters: tokenizationParameters,
        allowedPaymentMethods: allowedPaymentMethods,
        cardRequirements: {
            allowedCardNetworks: allowedCardNetworks
        }
    };
}

//transaction info
function getGoogleTransactionInfo() {
    return {
        currencyCode: 'RUB',
        totalPriceStatus: 'FINAL',
        totalPrice: '10.00'
    };
}

//button handler
function onGooglePaymentButtonClicked() {
    var paymentDataRequest = getGooglePaymentDataConfiguration();
    paymentDataRequest.transactionInfo = getGoogleTransactionInfo();

    var paymentsClient = getGooglePaymentsClient();
    paymentsClient.loadPaymentData(paymentDataRequest)
        .then(function (paymentData) {
            processPayment(paymentData);
        });
}            

//payment processing
function processPayment(paymentData) {
    var data = {
        cryptogram: JSON.stringify(paymentData.paymentMethodToken.token)
    };

    // send a request to your server, and then request the CloudPayments API
    // to make a payment
    $.post("/GooglePay/Pay", data).then(function (result) {
        if (result.Success) {
            //payment successful
        } else {
            if (result.Model.PaReq) { 
                //3-d secure required
            } else {
                //payment declined
            }
        }
    });
}

At the end of the page you need to place a script to call the Google Pay API functions:

<script async src="https://pay.google.com/gp/p/js/pay.js" onload="onGooglePayLoaded()"></script>

See also:

Google Pay Terms of Use

You can use Google Pay technology with CloudPayments on websites and mobile applications subject to the following requirements:

Integration Scenarios

The system offers various integration options from very simple to infinitely functional depending on the requirements.

Payment Form

If you do not need to check payments before payment and record the fact after the payment:

Payment Registering

If you need to register payments in your system, then your actions are:

Payment Checking and Registering

If you need to check and register payments in your system, your actions are:

Recurrent Payments for ISP's

The payment solution is suitable for Internet providers, telecom operators and telecoms. Notifications for checking and registering payments can be configured both in CloudPayments format and in QIWI format (OSMP).

Code:

    this.paySample3 = function () {
    var widget = new cp.CloudPayments();

    var data = {};
    var auto = $('#recurrent-sample-3').is(':checked'); //checking

    if (auto) { //enabling the subscription

        var date = new Date(); //current date
        date.setMonth(date.getMonth() + 1); //next month
        date.setDate(date.getDate() - 1); //minus one day

        var recurrent = { interval: 'Month', period: 1, startDate: date }; //once a month starting from the next month minus one day

        data.cloudPayments = {
            recurrent: recurrent
        }
    }

    var amount = parseFloat($('#amount-sample-3').val());
    var accountId = $('#account-sample-3').val();

    widget.charge({ // options
        publicId: 'test_api_00000000000000000000002', //id from Back Office
        description: 'Top up the account number ' + accountId, //purpose/justification
        amount: amount, 
        currency: 'RUB', 
        accountId: accountId, //Payer's ID (required for subscription)
        data: data
    },
    function (options) { // success
        //action upon successful payment
    },
    function (reason, options) { // fail
        //action upon unsuccessful payment
    });
};

$('#checkout-sample-3').click(paySample3);

Recurrent Payments for Charities

The payment solution is suitable for charitable foundations. The name, surname, phone number, e-mail and any other data from the form will be saved in the widget and transferred to your server via Pay notification.

Code:

this.paySample4 = function () {
    var widget = new cp.CloudPayments();

    var data = { //donator data
        name: $('#name-sample-4').val(),
        lastName: $('#lastName-sample-4').val(),
        phone: $('#phone-sample-4').val()
    };

    var auto = $('#recurrent-sample-4').is(':checked'); //check

    if (auto) { //enabling the subscription
        data.cloudPayments = {
            recurrent: { interval: 'Month', period: 1 } //once a month starting the next month
        }
    }

    var amount = parseFloat($('#amount-sample-4').val());
    var accountId = $('#email-sample-4').val();

    widget.charge({ // options
        publicId: 'test_api_00000000000000000000002', //id from Back Office
        description: 'Donation to a fund ...', //purpose
        amount: amount, 
        currency: 'RUB', 
        accountId: accountId, //Payer's ID (required for subscription)
        email: accountId,
        data: data
    },
    function (options) { // success
        //action upon successful payment
    },
    function (reason, options) { // fail
        //action upon unsuccessful payment
    });
};

$('#checkout-sample-4').click(paySample4);

Payment by Installments

The payment solution is suitable for companies selling goods and services with the possibility of payment by installments.

Code:

this.paySample5 = function () {
    var widget = new cp.CloudPayments();

    var amount = 12000; //by default 12,000 rubles at once
    var data = {};

    var payLater = $('#select-sample-5-later').is(':checked'); //check

    if (payLater) { //enabling the subscription
        data.cloudPayments = {
            recurrent: { interval: 'Month', period: 1, amount: 1000, maxPeriods: 6 } //6 months for 1000 rubles starting the next month
        };
        amount = 6000; //The amount of the first payment is 6000 rubles.
    }

    widget.charge({ // options
        publicId: 'test_api_00000000000000000000002', //id from Back Office
        description: 'Payment ...', //purpose
        amount: amount, 
        currency: 'RUB', 
        accountId: 'user@example.com', //Payer's ID (required for subscription)
        data: data
    },
    function (options) { // success
        //action upon successful payment
    },
    function (reason, options) { // fail
        //action upon unsuccessful payment
    });
};

$('#checkout-sample-5').click(paySample5);

Regular recurrent payments

If you need to charge a fee from your customers on a regular basis, according to a schedule, the scenario may be also as follows:

recurring1

One Click Payment(Recurring)

If you need to save the card data on the payment gateway side for further payment in one click without entering the card data and without 3-D Secure, the scenario may be as follows:

1cl-1

If the user agrees, save the card mask (type and last 4 digits) and the token after the payment in his profile. The card and token parameters are returned by the system in Pay notifications and in API payment requests reply.


1cl-2

If the user selects a previously used card, call a payment method by a token via the API.

1cl-3

If the user does not want to pay with an attached card anymore, remove the mask and token from his profile.

PCI DSS

PCI DSS is an information security standard developed for payment card industry for organizations that handle branded cards (Visa and MasterCard). All the companies that accept cards for payment must be in compliance to that standard . Some of them need to confirm their compliance.

Compliance with the Requirements

The main requirement of the standard is to limit access to payment card data as much as possible. The best solution is not to have access to them at all, and instead use certified providers to receive payments. In practice, this means that you can neither request nor send card numbers. If a customer calls, says that the payment does not go through and starts dictating the number, you need to interrupt it. If you send by mail / skype - delete the message and ask that it no longer do so.

The protected data includes the full card number and code CVV2 / CVC2 (the last 3 digits on the back side). The owner's name, expiration date and masked card number (the first 6 and last 4 digits) do not need to be protected according to the requirements of the standard so they can be used within reasonable limits.

PCI DSS Compliance with CloudPayments

CloudPayments is a certified service provider with the highest level of PCI DSS compliance, granting the right to store payment card data and process more than 6 million payments annually. Confirmation of compliance takes place every year as part of a certification audit.

All CloudPayments payment tools are designed in such a way that when you use them, you automatically meet the security requirements. No need to take additional measures.

An exception is the acceptance of payments using the Checkout technology. To use, it is necessary to confirm compliance: fill out a self-assessment sheet and quarterly check the site for vulnerabilities with a special scanner.

Checkout Technology

Checkout — unique tokenization card technology for accepting payments on your website, in your form without embedded iframe elements, which gives maximum control and conversion of payment progress. Payment card data is encrypted in the buyer's browser, so your site is not involved in the processing and storage of card numbers, which significantly reduces the scope of application of PCI DSS requirements. However, the site affects the security of card data and to protect it, it is necessary to perform a scan at least once a quarter for searching viruses and vulnerabilities. Scanning must be done by an accredited vendor (ASV) from the list provided on the PCI Council website.

ASV Scan

ASV Scan - an automated scan of your site for vulnerabilities. The scanner checks for viruses, known vulnerabilities, such as XSS, SQL Injections, and so on, and then compiles a detailed report with instructions on how to fix problems, if they were detected..

The use of the scanner is necessary for receiving payments using the Checkout technology; for other tools: widget, mobile SDK, recurring and recurrent use is not required.

The choice of vendor for scanning remains at your discretion, but it must be from the list on the PCI website . If you have no preferences, we recommend using Trustwave - an international company, a recognized leader in information security.

Instructions for Trustwave ASV scanner

The annual cost of the package of services is $ 229 and includes a subscription to the scan, assistance in completing the self-assessment sheet, training materials and security policy.

You need to:

Online Cash Register

Federal Law №54

Federal Law №54 "On the use of cash registers", as amended on July 3, 2016, prescribes Internet services, when making an electronic payments (including by a bank card), to use cash registers and send online-receipts to a buyer at the time of calculation.

Law Basics

Online Fiscalization

CloudPayments offers its partners a cloud solution for online fiscalization of Internet payments and, within the framework of compliance with Federal Law №54 for any business, you will receive:

The Cash Register will be placed in the data center 24/7, with internet and power connections, working around the clock and without interruption. Our employees will monitor its technical condition and change fiscal stores in a timely manner, and special software will correct errors, open and close shifts on a schedule, put receipts in a cloud in a large load and be sure to send them to customers.

cloud-scheme

Online Register

We use "MicroPay-FAS" and "MicroPay-FS" cash registers with the connection to any operator of fiscal data.

cash_registers

Technology Demonstration

The example of payment by a card with automatic receipt generation and sending to an email address or telephone.

Cost

The cost of online fiscalization and maintenance services can be found on the website CloudKassir and/or clarified with your account manager.

Onboarding Procedure

To activate the online fiscalization service, you need:

After signing the contract and paying the bill, you will get a Cash Register and FN number for registration with the Federal Tax Service.

Online Receipt Format for Payment Methods

The data for the receipt must be sent in json format as shown below:

var receipt = {
            "Items": [//commodity items
                {
                    "label": "Product №1", //item name
                    "price": 100.00, 
                    "quantity": 1.00, 
                    "amount": 100.00, 
                    "vat": 0, //vat rate
                    "method": 0, // tag-1214 sign of the calculation method
                    "object": 0, // tag-1212 sign of the calculation object - sign of the calculation object, work, service, payment, payout, or another calculation object
                    "measurementUnit": "шт" 
                }, {
                    "label": "Product №2", //item name
                    "price": 200.00, 
                    "quantity": 2.00, 
                    "amount": 300.00, //amount with 25% discount
                    "vat": 10, //vat rate
                    "method": 0, // tag-1214 sign of the calculation method
                    "object": 0, // tag-1212 sign of the calculation object - sign of the calculation object, work, service, payment, payout, or another calculation object
                    "measurementUnit": "шт" 
                }, {
                        "label": "Product №3", //item name
                        "price": 300.00, 
                        "quantity": 3.00,
                        "amount": 900.00, 
                        "vat": 20, //vat rate
                        "method": 0, // tag-1214 sign of the calculation method
                        "object": 0, // tag-1212 sign of the calculation object - sign of the calculation object, work, service, payment, payout, or another calculation object
                        "measurementUnit": "шт", 
                        "AgentSign": 6, // tag OFD 1057, 1222
                        "AgentData": { //tag OFD 1223
                            "AgentOperationName": null, // name of the operation of the bank payment agent or bank payment subagent, tag OFD 1044
                            "PaymentAgentPhone": null,  //  payment agent telephone, tag OFD 1073
                            "PaymentReceiverOperatorPhone": null, // tag OFD 1074
                            "TransferOperatorPhone": null, // tag OFD 1075
                            "TransferOperatorName": null, // tag OFD 1026
                            "TransferOperatorAddress": null, // tag OFD 1005
                            "TransferOperatorInn": null // tag OFD 1016
                        },
                        "PurveyorData": { //tag OFD 1224
                            "Phone": "+74951234567", // tag OFD 1171
                            "Name": "ООО Ромашка", // tag OFD 1225
                            "Inn": "1234567890" // tag OFD 1226
                        }
                    }
            ],
            "calculationPlace": "www.my.ru", //calculation place, by default taken from the cash register
            "taxationSystem": 0, //optional, if you have one taxation system
            "email": "user@example.com", //buyer's e-mail , if you need to send a email with the receip
            "phone": "", //buyer's phone number in free format, if you need to send a link on the receipt via SMS
            "isBso": false, //if receipt is a form of strict accountability
            "amounts":
            {
                "electronic": 1300.00, // the amount of payment by electronic money
                "advancePayment": 0.00, // prepayment amount (offset of advance payment) (2 decimal places)
                "credit": 0.00, // postpay amount (on credit) (2 decimal places)
                "provision": 0.00 // the amount of payment by the reciprocal grant (certificates, other physical values) (2 decimal places)
            }
        }


var data = { //the contents of the data element
    "cloudPayments": {
      "customerReceipt": receipt, //online-receipt
    }
}

Online Receipt Format Parameters

Name Parameters
Taxation options see the reference
VAT rate see the reference
Calculation methods see the reference
Calculation objects see the reference
Agent sign see the reference
Agent data see the reference
Purveyor data see the reference

Fiscal Data Operators

The table below shows the fiscal data operators that online cash registers can work with.

Code Operator's name
PeterService LLC "PS ST"
FirstOfd First OFD
Taxcom Taxcom
PlatformaOfd Platforma OFD
OfdYa OfdYa
OfdYandex Yandex OFD
Garantexpress Garant OFD
OfdAstralNalog Astral OFD
Sbis Company "TENZOR", Ltd.

Terms and Conditions of Online-Receipt Generation

Data for an online receipt can be transferred to the widget parameters, with payment by a cryptogram or by a token, with payment confirmation, when making a refund, and also through a special CloudKassir API(Ru).

Receipt Types and Settlement Signs

When transferring data for an online receipt to a widget or payment methods, the system generates 2 types of checks in automatic mode:

Sending a Receipt to a Buyer

At the choice of a buyer, an online receipt must be sent by e-mail or SMS (Viber / WhatsApp / Telegram) message to the phone number. The receipt can be sent by CloudPayments system automatically, provided that the e-mail address or phone number of a buyer been sent, or you can send a receipt manually. The system sends all the necessary details in the Receipt notification about generated receipts.

The Moment of Sending a Receipt

A receipt must be sent to the buyer at the time of settlement. For Single message scheme payment, a receipt is generated immediately once the payment has been completed, for dual message scheme payments - upon confirmation of the operation.

Online Receipt Testing

When operating in test mode, cash receipts will be generated in a demo Cash Register with a debug fiscal drive. You can transfer data for an online receipt when paying in test mode and check the operation of the online cash register.



Testing

Once you have an access to Back Office, it is in a test mode already, which means that payments and other operations will take place in emulation mode.

For testing, you can use the following card data:

Type Card Number Payment result Payment result by Token
Card Visa with 3-D Secure 4242 4242 4242 4242 Successful result Successful result
Card MasterCard with 3-D Secure 5555 5555 5555 4444 Successful result Successful result
Card Visa with 3-D Secure 4012 8888 8888 1881 Insufficient funds
Card MasterCard with 3-D Secure 5105 1051 0510 5100 Insufficient funds
Card Visa without 3-D Secure 4111 1111 1111 1111 Successful result Insufficient funds
Card MasterCard without 3-D Secure 5200 8282 8282 8210 Successful result Insufficient funds
Card Visa without 3-D Secure 4000 0566 5566 5556 Insufficient funds
Card MasterCard without 3-D Secure 5404 0000 0000 0043 Insufficient funds

Apple Pay Testing

In test mode, the system accepts payments on any card binded to Apple Pay for less than 10,000 rubles with a successful result (but does not charge money) and rejects payments in excess of 10,000 rubles with the error "Insufficient funds".

Online Cash Register Testing

When operating in test mode, cash receipts will be generated in a test online cash register with a debug fiscal drive. By default test online cash registers are disabled. If you need to enable it, please ask your manager or write on support@cloudpayments.ru.

Reference

Error Codes

Below are the error codes that determine the reason of the payment declined.

Payment Widget shows codes to payer automatically. Via API error codes returns in parameter CardHolderMessage.

Code Name Reason Message for payer
5001 Refer To Card Issuer Issuer declined the operation Contact your bank or use another card.
5005 Do Not Honor Issuer declined without explanation
- CVV code is incorrect on MasterCard;
- Issuer Bank internal limitations;
- card is locked or not activated yet;
- card is not allowed for online payments or have no 3Dsecure.
Contact your bank or use another card
5006 Error Network failure to perform an operation or incorrect CVV code Check if the entered card data is correct or use another card
5012 Invalid Transaction The card is not intended for online payments Contact your bank or use another card
5013 Amount Error Too small or too large transaction amount Check the correctness of the amount
5030 Format Error Error on the side of the acquirer - incorrectly formed transaction Try again later
5031 Bank Not Supported By Switch Unknown card issuer Use another card
5034 Suspected Fraud Issuer failure - fraud suspected Contact your bank or use another card
5041 Lost Card Lost Card Contact your bank or use another card
5043 Stolen Card Stolen Card Contact your bank or use another card
5051 Insufficient Funds Insufficient Funds Insufficient Funds
5054 Expired Card Card expired or expiration date is incorrect Check if the entered card data is correct or use another card
5057 Transaction Not Permitted Card limitation
— internal limitations of the Issuer
— card is locked or not activated yet;
— card is not allowed for online payments or have no 3Dsecure.
Contact your bank or use another card
5065 Exceed Withdrawal Frequency Exceed Withdrawal Frequency Contact your bank or use another card
5082 Incorrect CVV Incorrect CVV code Incorrect CVV code
5091 Timeout The Issuer is not available Try again later or use another card
5092 Cannot Reach Network The Issuer is not available Try again later or use another card
5096 System Error Acquiring bank or network error Try again later
5204 Unable To Process The operation cannot be processed for other reasons Contact your bank or use another card
5206 Authentication failed Authentication failed Contact your bank or use another card
5207 Authentication unavailable Authentication unavailable Contact your bank or use another card
5300 Anti Fraud Acquirer Transaction Limits Use another card

Operation Types

The table below contains the operation type codes in the notifications.

Code Name
Payment Payment
Refund Refund
CardPayout Payout on the card

Transaction Statuses

The table below contains transaction statuses, usage conditions and possible actions.

Status Description Use Possible actions
AwaitingAuthentication Awaiting of Authentication Once the payer's transferred to the issuer's website until 3-D Secure results received No
Authorized Authorized Once authorized Confirm, Cancel
Completed Completed Once operation confirmed Refund
Cancelled Cancelled In case of cancellation of the operation No
Declined Declined Impossible to complete the transaction (Insufficient Funds, etc) No

Subscription Statuses (Recurrents)

The table below contains subscription statuses, usage conditions and possible actions.

Status Description Use Possible actions
Active Subscription active After creating and another successful payment Cancel
PastDue Subscription expired After one or two consecutive unsuccessful payment attempts Cancel
Cancelled Cancelled In case of cancellation upon request No
Rejected Rejected In the case of three unsuccessful payment attempts, going in a row No
Expired Done In case of completion of the maximum number of periods (if specified) No

Currency List

Our partners accept payments in rubles, US dollars, euros, pounds sterling and 54 other currencies of the world.

The table below contains the names of the currencies and their codes for use in the currency parameter of Widget or API.

Name Code
Russian ruble RUB
Euro EUR
US dollar USD
Pound sterling GBP
Ukrainian hryvnia UAH
Belarusian ruble (not in use sicne 1st of July 2016) BYR
Belarusian ruble BYN
Kazakh tenge KZT
Azerbaijani manat AZN
Swiss frank CHF
Czech Koruna CZK
Canadian dollar CAD
Polish zloty PLN
Swedish crown SEK
Turkish lira TRY
Chinese yuan CNY
Indian rupee INR
Brazilian real BRL
South african rand ZAL
Uzbek Sum UZS
Bulgarian Lev BGL

If the currency you need is not listed, email us at support@cloudpayments.ru and we will update it.

Taxation Systems

The table below contains the options for tax systems of legal entities and individual entrepreneurs, which are used in the generation of online-receipts.

Code Taxation System
0 General taxation system
1 Simplified Tax System (Income)
2 Simplified taxation system (Income minus Expense)
3 A single tax on imputed income
4 Single agricultural tax
5 Patent taxation system

VAT values

Code Description
null or not specified no VAT
0 VAT 0%
10 VAT 10%
20 VAT 20%
110 estimated VAT 10/110
120 estimated VAT 20/120

Calculation Methods

Code Description Comment
0 Unknown unknown calculation method
1 FullPrepayment Prepayment 100%
2 PartialPrepayment -
3 AdvancePay Prepaid expense
4 FullPay FullPayment
5 PartialPayAndCredit Partial payment and credit
6 Credit Giving in credit
7 CreditPayment -

Calculation Objects

Code Description
0 Unknown
1 Commodity
2 ExcisedCommodity
3 Job
4 Service
5 GamblingBet
6 GamblingWin
7 LotteryTicket
8 LotteryWin
9 RidAccess
10 Payment
11 AgentReward
12 Composite
13 Another

AgentSign. OFD Tag 1057, 1222

For the correct generation of online-receipt you need: In each heading, specify agent data (Tag 1223) and supplier data (Tag 1224). To transfer not more than 5 such items per one online-receipt (technical limitation of the online-cash register).

Code Description
0 "Bank payment agent", Provision of services by the user, which is a bank payment agent
1 "Bank payment subagent", Provision of services by the user, which is a bank payment subagent
2 "Paying agent", the provision of services by the user, who is a payment agent
3 "Payment subagent", Provision of services by the user, which is a payment subagent
4 "Attorney", Provision of services by the user who is an attorney
5 "Commissioner", the provision of services by the user, who is the commissioner
6 "Agent", Provision of services by a user who is an agent and is not a bank payment agent (subagent), payment agent (subagent), attorney, commission agent

AgentData. OFD Tag 1223

Parameter Type Description
AgentOperationName String The name of the operation of the bank payment agent or bank payment subagent, OFD Tag 1044
PaymentAgentPhone String Payment agent phone, OFD Tag 1073
PaymentReceiverOperatorPhone String Phone of taking payment operator, OFD Tag 1074
TransferOperatorPhone String Phone of money transfer operator, OFD Tag 1075
TransferOperatorName String The name of money transfer operator, ODF Tag 1026
TransferOperatorAddress String Address of money transfer operator, OFD Tag 1005
TransferOperatorInn String TIN of the money transfer operator, OFD Tag 1016

PurveyorData. OFD Tag 1224

Parameter Type Description
Phone String Supplier's phone number, OFD Tag 1171
Name String Supplier's Name, OFD Tag 1225
Inn String Supplier's TIN, OFD Tag 1226

Timezone Codes

The table below contains time zone codes for time conversion.

Code Description
HST (UTC-10:00) Hawaii
AKST (UTC-09:00) Alaska
PST (UTC-08:00) Pacific Time (US and Canada)
MST (UTC-07:00) Mountain time (USA and Canada)
CST (UTC-06:00) Central time (USA and Canada)
EST (UTC-05:00) Eastern time (USA and Canada)
AST (UTC-04:00) Atlantic Time (Canada)
BRT (UTC-03:00) Brazil
UTC (UTC) UTC Format
GMT (UTC) Dublin, Lisbon, London, Edinburgh
CET (UTC+01:00) Amsterdam, Berlin, Bern, Vienna, Rome, Stockholm
CET (UTC+01:00) Belgrade, Bratislava, Budapest, Ljubljana, Prague
CET (UTC+01:00) Brussels, Copenhagen, Madrid, Paris
CET (UTC+01:00) Warsaw, Zagreb, Sarajevo, Skopje
EET (UTC+02:00) Athens, Bucharest
EET (UTC+02:00) Vilnius, Kiev, Riga, Sofia, Tallinn, Helsinki
EET (UTC+02:00) Eastern Europe
EET (UTC+02:00) Kaliningrad (RTZ 1)
MSK (UTC+03:00) Volgograd, Moscow, St. Petersburg (RTZ 2)
MSK (UTC+03:00) Minsk
AZT (UTC+04:00) Baku
AMT (UTC+04:00) Yerevan
SAMT (UTC+04:00) Izhevsk, Samara (RTZ 3)
GET (UTC+04:00) Tbilisi
TJT (UTC+05:00) Ashgabat, Tashkent
YEKT (UTC+05:00) Yekaterinburg (RTZ 4)
ALMT (UTC+06:00) Astana, Almaty
NOVT (UTC+06:00) Novosibirsk (RTZ 5)
KRAT (UTC+07:00) Krasnoyarsk (RTZ 6)
HKT (UTC+08:00) Hong Kong, Beijing, Urumqi, Chongqing
IRKT (UTC+08:00) Irkutsk (RTZ 7)
SGT (UTC+08:00) Kuala Lumpur, Singapore
ULAT (UTC+08:00) Ulaanbaatar
YAKT (UTC+09:00) Yakutsk (RTZ 8)
VLAT (UTC+10:00) Vladivostok, Magadan (RTZ 9)
SAKT (UTC+11:00) Chokurdah (RTZ 10)
ANAT (UTC+12:00) Anadyr, Petropavlovsk-Kamchatsky (RTZ 11)

Notification Types

The table below contains the types of notifications.

Code Name
Check Check
Pay Pay
Fail Fail
Confirm Confirm
Refund Refund
Recurrent Recurrent
Receipt Receipt
Cancel Cancel
Kkt Kkt