General info

Version 1.5 of Aug 6, 2014

Key terms and definitions
  • System — CloudPayments payment gateway.
  • Merchant — company which is using the system.
  • API — software used to operate the system, which is found at
  • Card — bank card which is using Visa or MasterCard payment service
  • Account — Personal account of the merchant, located at.
  • Acquirer — settlement bank.
  • Issuer — bank which issued the card.
  • Holder — customer which was issued a card by the issuer.
  • Widget — payment form provided by the system and which is used to enter the card information by the holder and subsequent authorization.
  • 3-D Secure — A protocol used to verify the holder by the issuer.
Types of operations

The system offers two types of operations: payment and return of funds (refund). In the first case, the money is transferred from the Holder’s account to the Merchant’s account, and in the second case the order is reversed. Merchant is responsible for the return of funds in case of request from the customer to return the goods, and it is always associated with the payment completed, which has the amount paid and therefore the amount to be returned. Either all, or a part of the payment, can be returned. Usually, the money is returned to the Holder’s card on the same day, but depending on the Issuer, it may sometimes take up to 3 business days for the funds to be returned.

Unlike the refund, the payment operation can be cancelled. Merchant will refuse payment if there is an error in the payment: wrong amount paid, technical issues, etc. The payment can be cancelled only until the end of the calendar day on which the payment was made. The money on the holder’s account will be unblocked for any other use almost immediately.

Payment schemes

There are two payment schemes: one, and two-step – they are also called single message scheme (SMS) and dual message scheme (DMS).

Single-step payment is completed with one command, and based on the results the authorization is either accepter or declined, and the money will be withdrawn from the Holder’s account, to be added to the Merchant.

Two-step payment will have two different commands: one for authorizing, and second for withdrawal. After successful authorization, the amount specified in the transaction will be blocked (reserved) on the Holder’s account, meaning they will not be able to use it. The Merchant then has 10 days for confirmation of this operation, and the money will be then deducted. If the operation is not confirmed within 10 days, it will be automatically declined. Either all, or a part of the payment sum can be confirmed. Usually, two-step payments are used to receive a deposit payment from the payer, such as in rental services and hotels.

Depending on the settings, the system can automatically confirm two-step payments after a specified amount of days.

Payment methods
The payment can be done with the following methods:
  • Through a payment form — the widget.
    A script which is added to your website, it opens a secure payments form (Iframe) for entering the card details.

  • Through API with a card cryptogram.
    A checkout script is added on your site, which collects the card information from any form on the site, encrypts them, and creates a cryptogram for safe transfer of information between servers.

  • Through SDK for mobile apps.
    Integrate a mobile SDK into your app for iPhone, iPad or Android and accept card payments from your client’s phone or tablet.

  • Through API based on card token (recurring payments).
    After first payment done via a widget or a cryptogram, the system assigns a unique identifier to the card information – a token which can be safely stored and used for payments without further authorization (pay per click). The token is returned with a Pay notification and in the system response with the API request.
    The token is assigned for the card information and the client, so that to receive this token, payment parameters mus also include AccountId.

  • With a set-up regular payments (recurrent payments).
    After first payment and authorization for 1 US dollars used to check the card, the system assigns a token to card information, which is then used for creating a subscription plan for recurring payments. The payment is done automatically by the system, without verification by the client, according to the period specified, which can be once a week (once in several weeks), once a month (once in several months). If a scheduled payment fails, the system sends a notification and will try the payment again in 24 hours. After three failed attempts in a row, the system will cancel the subscription.
    When creating a plan, a maximum amount of payment periods can be specified, after which the subscription will be automatically cancelled. For example, 12 months with monthly payments, after which the system will cancel the subscription.
    The token is assigned for the card information and the client, so that to receive this token, payment parameters mus also include AccountId.
3-D Secure

3-D Secure is the common name for the programs ‘Verified by Visa’ and ‘MasterCard Secure Code’, from Visa and MasterCard payments systems, respectively. This program is used to verify the identity of the Holder (meaning this is a protection from unauthorized card use) by the Issuer before the payment. In reality, the payment steps will be as follows: the Holder specifies the card information, then an Issuer’s website will open, which will ask the Holder to enter a password or a secret code (which is usually sent by a SMS text message to Holder’s phone). If the code is specified correctly, the payment will be successful. If not, the system will decline the payment.

Sample form with 3-D Secure

3-D Secure is not shown with payments by all cards, but only with those, where the issuing bank supports this technology. Payments done with 3-D Secure are, without a doubt, more safe payment method.

Operation statuses

In the table below you can see the transaction statuses, how they can be used, and possible actions.

For payment operations:

Status Description Usage Possible Actions
AwaitingAuthentication Awaiting Authentication Awaiting 3-D Secure authentication results after payer is sent to issuer’s site. None
Authorized Authorized After receiving authorization Confirmation, Cancellation
Completed Completed After operation has been confirmed Cancellation (until the end of day), Refund
Cancelled Cancelled If operation was cancelled None
Declined Declined If operation cannot be completed (insufficient funds in the account, etc) None

Subscription statuses (recurrent payments)

In the table below you can see the subscription statuses, how they can be used, and possible actions.

Status Description Usage Possible Actions
Active Active After creation and successful payment Cancel
PastDue Past due After one or two subsequent unsuccessful payment attempts Cancel
Cancelled Cancelled If the request was cancelled None
Rejected Rejected After three unsuccessful subsequent payment attempts None
Expired Completed After the maximum amount of periods are finished (if specified) None