API

API
API is a system’s application programming interface to interact with TSP systems.

The interface runs at https://api.cloudpayments.ru and supports features to execute a payment, cancel a payment, to refund, terminate payments which have been executed using a dual message scheme, create and cancel subscriptions to recurrent payments, and also to send invoices by e-mail.

Architecture


API uses the REST architecture. Parameters are transmitted by the POST method in a request body in a «key=value» format or in JSON.

A format to send parameters is defined on the customer side and managed through a Content-Type request header:

  • For Content-Type' «key=value» parameters: application/x-www-form-urlencoded
  • For JSON Content-Type parameters: application/json


The system generates a reply in the JSON format, which includes at least two parameters: Success and Message:

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

The 1st parameter specifies a request result — successfully or not successfully, and the 2nd one can include an additional information.

Request Authentication


To authenticate a request, HTTP Basic Auth is used- login and password are sent in an HTTP request header. As a login a Public ID is used, and as the password an API Secret is used. You can get both these values in My Account.

If in a request a header with authentication data is not transferred, or incorrect data is transferred, the system will return an HTTP status 401 — Unauthorized.
 

API Idempotence


Idempotence is an API capability to provide the same result at a repeated request as that at the original one without any repeated processing. It means that you can send multiple requests to a system with the same identifier (ID), and only one of them will be processed, and all replies will be identical. Thus a protection against network errors is provided, which cause a creation of duplicated records and actions.

To enable an idempotence, you have to transfer in a request to API a header with an X-Request-ID key, which includes a unique identifier. A request ID is still generated on your side: it can be guid, a combination of an order number, date and amount, or any other value you need.

Each new request to be processed shall include a new X-Request-ID value. A processed result is stored in the system during 1 hour.
The system stores only successful request results.

Test method 

To verify an interaction with API, you can call a test method at https://api.cloudpayments.ru/test with no parameters. In reply, the method returns a request status.
Sample reply:

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

 

Payment with cryptogram 

 

For a payment with a cryptogram, generated by a Checkout, Apple Pay or Google Pay script, it is necessary to call a method at one of following addresses:


Request Parameters:

Parameter

Format

Use

Description

Amount

Numeric

Mandatory

Payment value

Currency

String

Mandatory

Currency: RUB/USD/EUR/GBP (see reference)

IpAddress

String

Mandatory

IP address of a payer

Name

String

Mandatory for all payments except Apple Pay and Google Pay

Name of a card holder (in Latin characters)

CardCryptogramPacket

String

Mandatory

Cryptogram of payment data

InvoiceId

String

Optional

Invoice or order number

Description

String

Optional

Payment description in a free form

AccountId

String

Optional

User identifier

Email

String

Optional

E-mail address of a payer, to which a payment slip will be sent

JsonData

Json

Optional

Any other data which will be related to a transaction, including instructions on how to create a subscription or generate an online check.
We reserved names of following parameters and display their contents in the transaction registry, downloaded in the My Account: name, firstName, middleName, lastName, nick, phone, address, comment, birthDate.

 

In its reply a server returns JSON with three components: a success field provides a request result, a message field provides an error description, a model entity provides an extended information.

Possible cases:

  • A non-correct request:


success is false
message is error description

  • A 3-D Secure authentication is required (not applicable for Apple Pay):


success is false
message is an information to perform an authentication

  • Transaction is rejected:


success — false
model is a transaction information and error code

  • Transaction is accepted:


success — true
model is a transaction information

Sample request for payment with cryptogram:

{
    "Amount":10,
    "Currency":"RUB",
    "InvoiceId":"1234567",
    "Description":"Оплата товаров в example.com",
    "AccountId":"user_x",
    "Name":"CARDHOLDER NAME",
    "CardCryptogramPacket":"01492500008719030128SMfLeYdKp5dSQVIiO5l6ZCJiPdel4uDjdFTTz1UnXY+3QaZcNOW8lmXg0H670MclS4lI+qLkujKF4pR5Ri+T/E04Ufq3t5ntMUVLuZ998DLm+OVHV7FxIGR7snckpg47A73v7/y88Q5dxxvVZtDVi0qCcJAiZrgKLyLCqypnMfhjsgCEPF6d4OMzkgNQiynZvKysI2q+xc9cL0+CMmQTUPytnxX52k9qLNZ55cnE8kuLvqSK+TOG7Fz03moGcVvbb9XTg1oTDL4pl9rgkG3XvvTJOwol3JDxL1i6x+VpaRxpLJg0Zd9/9xRJOBMGmwAxo8/xyvGuAj85sxLJL6fA=="
}

Sample reply: incorrect request

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

Sample reply: a 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
}
           

Sample reply: a transaction is rejected. A ReasonCode field provides an error code (see 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": "Оплата товаров в example.com",
        "JsonData": null,
        "CreatedDate": "\/Date(1401718880000)\/",
        "CreatedDateIso":"2014-08-09T11:49:41", //все даты в UTC
        "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": "Declined",
        "StatusCode": 5,
        "Reason": "InsufficientFunds", // причина отказа
        "ReasonCode": 5051, //код отказа
        "CardHolderMessage":"Недостаточно средств на карте", //сообщение для покупателя
        "Name": "CARDHOLDER NAME",
    },
    "Success": false,
    "Message": null
}
            

Sample reply: a transaction is accepted

{
    "Model": {
        "TransactionId": 504,
        "Amount": 10.00000,
        "Currency": "RUB",
        "CurrencyCode": 0,
        "InvoiceId": "1234567",
        "AccountId": "user_x",
        "Email": null,
        "Description": "Оплата товаров в example.com",
        "JsonData": null,
        "CreatedDate": "\/Date(1401718880000)\/",
        "CreatedDateIso":"2014-08-09T11:49:41", //все даты в UTC
        "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",
        "CardExpDate": "05/19",
        "CardType": "Visa",
        "CardTypeCode": 0,
        "Issuer": "Sberbank of Russia",
        "IssuerBankCountry": "RU",
        "Status": "Completed",
        "StatusCode": 3,
        "Reason": "Approved",
        "ReasonCode": 0,
        "CardHolderMessage":"Оплата успешно проведена", //сообщение для покупателя
        "Name": "CARDHOLDER NAME",
        "Token": "a4e67841-abb0-42de-a364-d1d8f9f4b3c0"
    },
    "Success": true,
    "Message": null
}
            

 

3-D Secure Processing

 

To perform a 3-D Secure authentication, it is necessary to redirect a payer to an address specified in the AcsUrl  parameter of a server reply with following parameters:

  • MD is a TransactionId parameter from a server reply
  • PaReq is a server reply's parameter with the same name
  • TermUrl is an address on your web site to return a payer after authentication

Characters in a parameter name are case-sensitive.

Sample form:

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

After authentication, the payer will be returned on TermUrl with MD and PaRes parameters, send using the POST method.

To complete a payment, it is necessary to call the method at https://api.cloudpayments.ru/payments/cards/post3ds with following parameters:

       

Parameter

Format 

Use

Description

TransactionId Int

Mandatory

MD parameter value

PaRes String Mandatory

Value of the parameter with the same name

In reply to a correctly generated request, the server will return successful transaction or rejected transaction information. 

Payment with token (recurring) 

 

For a payment with token it is necessary to call a method at one of following URLs:

 

 Parameter

 Format

Use

Discription

Amount

Numeric

Mandatory

Payment value

Currency

String

Mandatory

Currency: RUB/USD/EUR/GBP (see reference)

AccountId

String

Mandatory

User identifier

Token

String

Mandatory

Token

InvoiceId

String

Optional

Invoice or order number

Description

String

Optional

Payment function in a free form

IpAddress

String

Optional

IP address of a payer

Email

String

Optional

E-mail address of a payer, to which a payment slip will be sent

JsonData

Json

Optional

Any other data which will be related to a transaction, including instructions on how to create a subscription or generate an online check. We reserved names of following parameters and display their contents in the transaction registry, downloaded in the My Account: name, firstName, middleName, lastName, nick, phone, address, comment, birthDate

.

In its reply a server returns JSON with three components: a success field provides a request result, a message field provides an error description, a model entity provides an extended information.

Possible cases:

  • A non-correct request:
    success is false
    message is error description

  • Transaction is rejected:
    success — false
    model is a transaction information and error code

  • Transaction is accepted:
    success — true
    model is a transaction information

Sample request for payment with token:

{
    "Amount":10,
    "Currency":"RUB",
    "InvoiceId":"1234567",
    "Description":"Оплата товаров в example.com",
    "AccountId":"user_x",
    "Token":"a4e67841-abb0-42de-a364-d1d8f9f4b3c0"
}

Sample reply: incorrect request

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

Sample reply: a transaction is rejected. A ReasonCode field provides an error code (see reference)

{
    "Model": {
        "TransactionId": 504,
        "Amount": 10.00000,
        "Currency": "RUB",
        "CurrencyCode": 0,
        "InvoiceId": "1234567",
        "AccountId": "user_x",
        "Email": null,
        "Description": "Оплата товаров в example.com",
        "JsonData": null,
        "CreatedDate": "\/Date(1401718880000)\/",
        "CreatedDateIso":"2014-08-09T11:49:41", //все даты в UTC
        "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": "Declined",
        "StatusCode": 5,
        "Reason": "InsufficientFunds", //причина отказа
        "ReasonCode": 5051,
        "CardHolderMessage":"Недостаточно средств на карте", //сообщение для покупателя
        "Name": "CARDHOLDER NAME",
    },
    "Success": false,
    "Message": null
}

Sample reply: a transaction is accepted

{
    "Model": {
        "TransactionId": 504,
        "Amount": 10.00000,
        "Currency": "RUB",
        "CurrencyCode": 0,
        "InvoiceId": "1234567",
        "AccountId": "user_x",
        "Email": null,
        "Description": "Оплата товаров в example.com",
        "JsonData": null,
        "CreatedDate": "\/Date(1401718880000)\/",
        "CreatedDateIso":"2014-08-09T11:49:41",  //все даты в UTC
        "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":"Оплата успешно проведена", //сообщение для покупателя
        "Name": "CARDHOLDER NAME",
        "Token": "a4e67841-abb0-42de-a364-d1d8f9f4b3c0"
    },
    "Success": true,
    "Message": null
}

 

Payment confirmation 

 

For payments, which have been carried out using a dual message scheme, a payment confirmation is required, which can be executed through My Account or an API method call.

The method runs at https://api.cloudpayments.ru/payments/confirm and accepts following parameters:

 

Parameter

Format

Use

Description

TransactionId

Int

Mandatory

Transaction number in a system

Amount

Numeric

Mandatory

A confirmation value in a transaction currency

JsonData

Json

Optional

Any other data which will be related to a transaction, including instructions on how to generate an online check.

 

Sample request:

 

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

Sample reply:

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


A payment cancellation can be executed through My Account or an API method call. The method runs at https://api.cloudpayments.ru/payments/void and accepts a single parameter:

 

Parameter

Format

Use

Description

TransactionId

Int

Mandatory

Transaction number in a system

 

Sample request:

 

 

{"TransactionId":455}

 

Sample reply:

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

 

Refund

 

 

 

A refund can be executed through My Account or an API method call. The method runs at https://api.cloudpayments.ru/payments/refund and accepts following parameters:
 

 

Parameter

Format

Use

Description

TransactionId

Int

Mandatory

Payment transaction number

Amount

Numeric

Mandatory

A refund value in a transaction currency

JsonData

Json

Optional

Any other data which will be related to a transaction, including instructions on how to generate an online check.

 

Sample request:

 

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


Sample reply:

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


Payment can be made via an API method call. The method runs at https://api.cloudpayments.ru/payments/cards/topup with following parameters:
 

Parameter

Format

Use

Description

Token

String

Mandatory

Сard's token which has been assigned out by the system after the 1st payment

Amount

Numeric

Mandatory

Payment value

AccountId

String

Mandatory

User identifier

Currency

String

Mandatory

Currency: RUB

InvoiceId

String

Optional

Order number in your system

 

Sample request:

 

    "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"
}

Sample reply:
 

{
   "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
}

 

Pay out with token


Payment can be made via an API method call. The method runs at https://api.cloudpayments.ru/payments/token/topup with following parameters:

 

Parameter Format Application Description
Token String Required Card tokens issued by the system after the first payment
Amount Numeric Required Payment amount
AccountId String Required User ID
Currency String Required Currency: RUB
InvoiceId String Optional Order number in your system


Sample request:
 

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

Sample reply:
 

{
   "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
}



Viewing a Transaction Information

To view a transaction information, it is necessary to send a request to https://api.cloudpayments.ru/payments/get and specify a number a transaction in question:
 

Parameter

Format

Use

Description

TransactionId

Int

Mandatory

Transaction number

 

If a transaction with a specified number has been found, the system will display a related information.

Sample request:

 

{"TransactionId":"504"}

Sample reply:
 

{
    "Model": [{
        "TransactionId": 504,
        "Amount": 10.00000,
        "Currency": "RUB",
        "CurrencyCode": 0,
        "InvoiceId": "1234567",
        "AccountId": "user_x",
        "Email": null,
        "Description": "Оплата товаров в example.com",
        "JsonData": null,
        "CreatedDate": "\/Date(1401718880000)\/",
        "CreatedDateIso":"2014-08-09T11:49:41", //все даты в указанной временной зоне
        "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":"Оплата успешно проведена", //сообщение для покупателя
        "Name": "CARDHOLDER NAME",
    }],
    "Success": true,
    "Message": null
}


 

Check of Payment Status

To search for a payment and verify a status (see reference), it is necessary to send a request to https://api.cloudpayments.ru/payments/find and specify an order number for which a transaction has been generated:
 

Parameter

Format

Use

Description

InvoiceId

String

Mandatory

Order number

 

 

If a payment has been found using the specified order number, the system will display an information on a successful transaction, or rejected one. If some payments with the specified order number will be found, the system will return the information only about a last transaction.

 

 

Sample request:

{"InvoiceId":"123456789"}


Sample reply:

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


A verification of a payment status is redundant, and is makes sense only when a payment procedure failed, so an information was lost.

Downloading Transaction List

To download a list of transactions for a day it is necessary to send a request to https://api.cloudpayments.ru/payments/list and specify a date to select transactions:
 

Parameter

Format

Use

Description

Date

Date

Mandatory

Date of creating transactions

TimeZone

String

Optional

Code of a time zone, the default is UTC

 

All transactions, registered for a specified day, are downloaded. To make a metering more convenient, you can specify a code of a time zone (see reference)

 

Sample request:

{"Date":"2017-07-10", "TimeZone": "MSK"}


Sample reply:

{
    "Model": [{
        "TransactionId": 504,
        "Amount": 10.00000,
        "Currency": "RUB",
        "CurrencyCode": 0,
        "InvoiceId": "1234567",
        "AccountId": "user_x",
        "Email": null,
        "Description": "Оплата товаров в example.com",
        "JsonData": null,
        "CreatedDate": "\/Date(1401718880000)\/",
        "CreatedDateIso":"2014-08-09T11:49:41", //все даты в указанной временной зоне
        "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":"Оплата успешно проведена", //сообщение для покупателя
        "Name": "CARDHOLDER NAME",
    }],
    "Success": true,
}

Creating a subscription for recurrent payments

To subscribe a user for recurrent payments, it is necessary to send a request to https://api.cloudpayments.ru/subscriptions/create with following parameters:
 

Parameter

Format

Use

Description

Token

String

Mandatory

Сard's token which has been assigned out by the system after the 1st payment

AccountId

String

Mandatory

User identifier

Description

String

Mandatory

Payment function in a free form

Email

String

Mandatory

E-mail address of the payer

Amount

Numeric

Mandatory

Payment value

Currency

String

Mandatory

Currency: RUB/USD/EUR/GBP (see reference)

RequireConfirmation

Bool

Mandatory

If a true value is used, payments are made using the dual message scheme

StartDate

DateTime

Mandatory

Date and time of the 1st payment according to a schedule in the UTC time zone

Interval

String

Mandatory

Interval. Possible values are: Day, Week, Month

Period

Int

Mandatory

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

 

In reply to a correctly generated request, the system returns a successful transaction message and a subscription identifier.

Sample request:

{
   "token":"477BBA133C182267FE5F086924ABDC5DB71F77BFC27F01F2843F2CDC69D89F05",
   "accountId":"user@example.com",
   "description":"Ежемесячная подписка на сервис example.com",
   "email":"user@example.com",
   "amount":1.02,
   "currency":"RUB",
   "requireConfirmation":false,
   "startDate":"2014-08-06T16:46:29.5377246Z",
   "interval":"Month",
   "period":1
}


Sample reply:

 

{
   "Model":{
      "Id":"sc_8cf8a9338fb8ebf7202b08d09c938", //идентификатор подписки
      "AccountId":"user@example.com",
      "Description":"Ежемесячная подписка на сервис example.com",
      "Email":"user@example.com",
      "Amount":1.02,
      "CurrencyCode":0,
      "Currency":"RUB",
      "RequireConfirmation":false, //true для двустадийных платежей
      "StartDate":"\/Date(1407343589537)\/",
      "StartDateIso":"2014-08-09T11:49:41", //все даты в 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
}

 

Search for Subscriptions

To obtain a list of subscriptions for a specific account, it is necessary to send a request to https://api.cloudpayments.ru/subscriptions/find with a single parameter:
 

Parameter

Format

Use

Description

accountId

String

Mandatory

Account identifier


Sample request:

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

Sample reply:
 

{
  "Model": [
    {
      "Id": "sc_4bae8f5823bb8cdc966ccd1590a3b",
      "AccountId": "user@example.com",
      "Description": "Подписка на сервис",
      "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": "Подписка на сервис",
      "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
}

Modification of a Subscription for Recurrent Payments

To modify a previously created subscription, it is necessary to send a request to https://api.cloudpayments.ru/subscriptions/update with following parameters:
 

Parameter

Format

Use

Description

Id

String

Mandatory

Subscription identifier

Description

String

Optional

To modify a purpose of payment

Amount

Numeric

Optional

To modify a payment value

Currency

String

Optional

To modify a currency RUB/USD/EUR/GBP (see reference)

RequireConfirmation

Bool

Optional

To modify a payment scheme

StartDate

DateTime

Optional

To modify a date and time of the 1st (or next) payment in the UTC time zone

Interval

String

Optional

To modify an interval Possible values are: Week, Month

Period

Int

Optional

To modify a period. Together with an interval, 1 Month means once a month, and 2 Week once two weeks.

MaxPeriods

Int

Optional

To modify a maximum number of payments in a subscription

 

 

In reply to a correctly generated request, the system returns a successful transaction message and subscription parameters.

 

 

Sample request:

{
   "Id":"sc_8cf8a9338fb8ebf7202b08d09c938",
   "description":"Тариф №5",
   "amount":1200,
   "currency":"RUB"
}

Sample reply:

{
   "Model":{
      "Id":"sc_8cf8a9338fb8ebf7202b08d09c938", //идентификатор подписки
      "AccountId":"user@example.com",
      "Description":"Тариф №5",
      "Email":"user@example.com",
      "Amount":1200,
      "CurrencyCode":0,
      "Currency":"RUB",
      "RequireConfirmation":false, //true для двустадийных платежей
      "StartDate":"\/Date(1407343589537)\/",
      "StartDateIso":"2014-08-09T11:49:41", //все даты в 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
}

 

Cancellation of a Subscription for Recurrent Payments

 

 

To cancel a subscription for recurrent payments, it is necessary to send a request to https://api.cloudpayments.ru/subscriptions/cancel with following parameters:

 

 

Parameter

Format

Use

Description

Id

String

Mandatory

Subscription identifier

 

 

In reply to a correctly generated request, the system returns a successful transaction message.

 

 

Sample request:

{"Id":"sc_cc673fdc50b3577e60eee9081e440"}


Sample reply:
 

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

You also can provide a buyer with a link to the system's web site that is https://my.cloudpayments.ru/unsubscribe, where he can find and cancel regular payments himself.

Creating an invoice to be sent by e-mail

To generate a link to payment and a subsequent sending a notification by email to a payer's address, it is possible to use a method https://api.cloudpayments.ru/orders/create with following parameters:
 

Parameter

Format

Use

Description

Amount

Numeric

Mandatory

Payment value

Currency

String

Mandatory

Currency: RUB/USD/EUR/GBP (see reference)

Description

String

Mandatory

Payment function in a free form

Email

String

Optional

E-mail address of the payer

RequireConfirmation

Bool

Optional

If the true is used, a payment will be made using the dual message scheme

SendEmail

Bool

Optional

If the true value is used, a payer will receive an e-mail message with a link to the payment

InvoiceId

String

Optional

Order number in your system

AccountId

String

Optional

User identifier in your system

OfferUri

String

Optional

A link to an offer which will be shown at an order page

Phone

String

Optional

Phone number of a payer in any format

SendSms

Bool

Optional

If the true value is used, a payer will receive an SMS with a link to the payment

SendViber

Bool

Optional

If the true value is used, a payer will receive a Viber message with a link to the payment

CultureName

String

Optional

Notification language. Possible values are: "ru-RU", "en-US"

SubscriptionBehavior

String

Optional

To create a payment with a subscription. Possible values are: CreateWeekly, CreateMonthly

JsonData

Json

Optional

Any other data which will be related to a transaction, including instructions on how to generate an online check.

 

 

In reply to a correctly generated request, the system returns request parameters and a link to a payment.

 

 

Sample request:

{
    "Amount":10.0,
    "Currency":"RUB",
    "Description":"Оплата на сайте example.com",
    "Email":"client@test.local",
    "RequireConfirmation":true,
    "SendEmail":false
}

Sample reply:
 

{
    "Model":{
        "Id":"f2K8LV6reGE9WBFn",
        "Number":61,
        "Amount":10.0,
        "Currency":"RUB",
        "CurrencyCode":0,
        "Email":"client@test.local",
        "Description":"Оплата на сайте example.com",
        "RequireConfirmation":true,
        "Url":"https://orders.cloudpayments.ru/d/f2K8LV6reGE9WBFn",
    },
    "Success":true,
}

 

A message to a payer's phone can be sent using only one selected way: SMS or Viber.

Cancellation of a Created Invoice

To cancel a created invoice, it is necessary to send a request to https://api.cloudpayments.ru/orders/cancel with following parameters:

Parameter

Format

Use

Description

Id

String

Mandatory

Invoice identifier

 

 

In reply to a correctly generated request, the system returns a successful transaction message.

 

 

Sample request:

{"Id":"f2K8LV6reGE9WBFn"}


Sample reply:

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



 

Viewing Notification Settings


To view notification settings it is necessary to send a request to https://api.cloudpayments.ru/site/notifications/{Type}/get and specify a notification type:
 

Parameter

Format

Use

Description

Type

String

Mandatory

Notification type: Check/Pay/Fail etc. (see reference)

 

 

Sample reply to request for a Pay notification to be sent to 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
}



Modification of Notification Settings

To modify notification settings, it is necessary to send a request to https://api.cloudpayments.ru/site/notifications/{Type}/update with following parameters:
 

Parameter

Format

Use

Description

Type

String

Mandatory

Notification type: Check/Pay/Fail etc. (see reference)

IsEnabled

Bool

Optional

If the true value is used, then a notification is enabled. The default value is false.

Address

String

Optional, if IsEnabled=false, otherwise it is mandatory

Notification address (a valid SSL certificate is required for HTTPS).

HttpMethod

String

Optional

HTTP method to send notifications. Possible values are: GET, POST. The default value is GET.

Encoding

String

Optional

Notification encoding. Possible values are: UTF8, Windows1251. The default value is UTF8.

Format

String

Optional

Notification format. Possible values are: CloudPayments, QIWI, RT. The default value is CloudPayments.

 

 

Sample reply to a Pay notification to be sent to https://api.cloudpayments.ru/site/notifications/pay/update:
 

 

 

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

 

Sample reply:

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


Starting a session for a payment via Apple Pay

A session start is required to accept Apple Pay payments on web sites. It is not required for payments in mobile applications.

The method runs at https://api.cloudpayments.ru/payments/startsession and accepts following parameters:
 

Parameter

Format

Use

Description

ValidationUrl

String

Mandatory

URL, received from Apple JS

 

 

In reply to a correctly generated request, the system returns a reply, where Model entity includes a session for an Apple Pay payment in the JSON format.

 

 

Sample request:
 

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


Sample reply:
 

{"Success":true, Model:{SomeAppleStuff:1}}


 

Localization changed

 

By default, API generates messages for users in Russian. To receive replies, localized for other languages, specify CultureName in request parameters.

List of supported languages:

Language

Time zone

Code

Russian

MSK

ru-RU

English

CET

en-US

Latvian

CET

lv

Azerbaijani

AZT

az

Russian

ALMT

kk

Ukrainian

EET

uk

Polish

CET

pl