Login
На русском

API

API — is a programmable interface used for interacting with the Merchant’s systems.


The interface is located at the address https://api.cloudpayments.ru and supports the functions of processing the payment, cancelling the payment, refunds, completing payments done via two-step process, creating and cancelling subscriptions for recurrent payments, and sending bills by mail.

Architecture

API uses REST architecture. The parameters are send in POST method in the body of the request, in “key=value” format, or in JSON.


Choosing the format is determined on the client side, and is determined by the header of Content-Type request: Content-Type:

  • For “key=value” parameters in Content-Type: application/x-www-form-urlencoded
  • For JSON parameters in Content-Type: application/json

The system will respond in a JSON format, which will have at least two parameters: Success и Message:

The first parameter shows the result of the request – if it was successful or not, the second contains information if there is an error.

Request authentication

HTTP Basic Auth — is used for authenticating requests – sending login and password in the header of HTTP request. As a login, the Public ID is used, the password - API Secret. Both of these values can be obtained in merchant account.


If the request does not have a header with authentication information, or the information sent in the request is incorrect, the system will return a HTTP 401 status – Unauthorized.

Test method

To check interaction with API, you can call a test method at https://api.cloudpayments.ru/test without sending the parameters. The method will return a type of request.

Example of a response:

Cryptogram-based payments

To pay with a cryptogram of card information, you need to call a method from one of the following addresses:

Examples of requests:

Parameter Format Use Description
Amount Numeric Required Payment amount
Currency String Required Currency: RUB/USD/EUR/GBP
InvoiceId String Optional Order or invoice number
Description String Optional Payment description in any form
IpAddress String Required Payer’s IP address
AccountId String Optional User identifier
Email String Optional Email of payer, where a receipt of the payment will be sent
JsonData Json Optional Any data
Name String Required Card holder’s name
CardCryptogramPacket String Required Card data cryptogram


In return, the server will respond with JSON with three components: success — the result of the request message — field – description of an error, model object – additional information.


Possible options:

  • Request is done incorrectly:
    success — false
    message — error description
  • 3-D Secure authentication is required:
    success — false
    model — information to complete the authentication
  • Transaction declined:
    success — false
    model — information on transaction and error code
  • Transaction approved:
    success — true
    model — information on transaction

Example of request for payment with cryptogram:

Example of response: incorrect request.

Example of response: 3-D Secure authentication required:

Example of response: Transaction declined. ReasonCode is the error code (see list of errors)

Transaction accepted.

Processing 3-D Secure

To process 3-D Secure authentication, you need to send the payer to the address listed in AcsUrl response from server, with the transfer of the following parameters:

  • MD — parameter TransactionId from server response;
  • PaReq — parameter with the same name from server response;
  • TermURL — address on your website where the payer will return after authentication.

Form example:

After authenticating, the payer will be returned to TermUrl with MD and PaRes, parameters sent via POST method.


To complete the payment, you need to call a method from the address https://api.cloudpayments.ru/payments/cards/post3ds and send the following parameters:

Parameter Format Use Description
TransactionId Int Required Value of parameter MD
PaRes String Required Value of the same-name parameter

In return on the correctly formulated request, the server will send information about either a successful transaction, or about — a declined transaction.

Paying with token (recurring)

To pay with a token, you need to call a method from one of the following addresses:

Request parameters:

Parameter Format Use Description
Amount Numeric Required Payment amount
Currency String Required Currency: RUB/USD/EUR/GBP
InvoiceId String Optional Invoice or order number
Description String Optional Payment description in any form
AccountId String Required User identifier
Email String Optional Email of payer, where a receipt of the payment will be sent
JsonData Json Optional Any data
Token String Required Token


Server will send a JSON response with three components: success field – the result of the request, message —field – description of error, model object – additional information.


Possible options:

  • Request is formed incorrectly:
    success — false
    message — error description
  • Transaction declined:
    success — false
    model — information on transaction and error code
  • Transaction approved:
    success — true
    model — information on transaction

Example of request for paying with token:

Example of response: incorrect request.

Example of response: transaction declined. ReasonCode is error code (see: list of error codes))

Example of response: Transaction accepted.

Approving transactions

For payments done using two-step scheme, a transaction approval is required, that can be done through merchant’s account, or by calling an API method.


Method is located at https://api.cloudpayments.ru/payments/confirm and accepts the following parameters:

Parameter Format Use Description
TransactionId Int Required Transaction number in system
Amount Numeric Required Approval sum in transaction currency

Example of request:

Example of response:

Canceling payment

Payment can be cancelled in merchant’s account or by calling an API method. Method is located at https://api.cloudpayments.ru/payments/void and accepts only one parameter:

Parameter Format Use Description
TransactionId Int Required Transaction ID in the system

Example of request:

Example of response:

Refund of money

Refunds can be done in merchant’s account or by calling an API method. Method is located at https://api.cloudpayments.ru/payments/refund and accepts the following parameters:

Parameter Format Use Description
TransactionId Int Required Transaction ID in the system
Amount Numeric Required Refund amount in the currency of the original transaction

Example of request:

Example of response:

Creating subscription for recurrent payments

To subscribe a user for recurrent payments, you need to make a request to https://api.cloudpayments.ru/subscriptions/create with the following parameters:

Parameter Format Use Description
Token String Required Card token, which was given by the system after a first payment
AccountId String Required User identifier
Description String Required Description of payment in any form
Email String Required Payer’s email address
Amount Numeric Required Payment sum
Currency String Required Currency: RUB/USD/EUR/GBP
RequireConfirmation Bool Required If value is true, the payment will be completed using two-step scheme
StartDate DateTime Required Date and time of first payment according to schedule in UTC time
Interval String Required Payment interval. Possible values: Week, Month
Period Int Required Period of payments. Together with interval of 1 Month means 1 payment per month, 2 Week – once in two weeks
MaxPeriods Int Optional Maximum number of payments in a subscription

For a valid request the system will return a response about a successful operation and a subscription identifier.

Sample request:

Response:

Requesting information on subscription

To receive information about subscription status, you need to make a request to https://api.cloudpayments.ru/subscriptions/get with only one parameter:

Parameter Format Use Description
Id String Required Subscription ID

Sample request:

Response:

Cancelling subscription for recurring payments

To cancel a subscription for recurring payments, you need to make a request to https://api.cloudpayments.ru/subscriptions/cancel with the following parameters:

Parameter Format Use Description
Id String Required Subscription ID

For a valid request the system will return a response that the operation has been completed successfully.

Sample request:

Response:

Creating an invoice for sending via mail

To create a web address to pay the invoice and have payer notified by email, you need to make a request to https://api.cloudpayments.ru/orders/create with following parameters:

Parameter Format Use Description
Amount Numeric Required Payment sum
Currency String Required Currency: RUB/USD/EUR/GBP
Description String Required Payment description in any form
Email String Required Payer’s email address
RequireConfirmation Bool Required If value is true – the payment will be done using two-step scheme
SendEmail Bool Required If value is true – a notification will be sent to the payer's email

For a valid request the system will return the request parameters and a web address to pay the invoice.

Sample request:

Response: