This section provides answers to questions that are commonly asked by the merchants' technical specialists.

These questions are divided into the following groups:

  • Integration covers questions about integration process including configuration and testing of various functionalities.
  • Payments covers questions about processing different types of payments, operations, and performing procedures as well as the rules for specifying different parameters in requests.
  • Callbacks covers questions about callbacks sent from the payment platform including their parameters and configuration.
  • Results covers questions about control and interpretation of different payment results, operations, and procedures performed within the platform.

If the information provided here and in other sections of the documentation is not enough to solve your problems, contact our specialists:

  • with business and financial issues (the cost of services, calculating commissions, working with balance sheets, and other questions), contact your key account manager;
  • with technical issues (working with different interfaces, making requests, and other questions), contact the technical support specialists (support@ecommpay.com).


Figure: What is PCI DSS for and how do I comply with its requirements?

Payment Card Industry Data Security Standard (PCI DSS) is a standard for the proper protection of payment card data. It is developed by the PCI Security Standards Council (PCI SSC) and sets requirements for all companies involved in processing, storing, or transmitting payment card data. Complying with the PCI DSS requirements is absolutely mandatory: no parties involved in processing card payments are allowed to process such payments otherwise.

To prove the compliance with the PCI DSS requirements and be allowed to process card payments, merchants are required to provide the corresponding documents to payment systems (such as Visa, Mastercard, and Amex) in time, directly or through providers. Depending on a payment system, there can be different requirements to such documents with regards to the data breach incidents and other cases. Therefore, the necessity for a particular merchant to provide certain documents is considered on a case-by-case basis.

In the case of the Visa and Mastercard payment systems, the PCI DSS compliance documents should be provided to ECommPay. Thus the following documents are required:

  • From all merchants—the ASV scan report.

    The ASV scanning must be performed by the authorised scanning service providers (PCI SSC Approved Scanning Vendor, ASV) quarterly and after every significant change in the network infrastructure. The ECommPay merchants can select these providers on their own and, if relevant, have the scanning procedure performed by the ECommPay partner. To have the scanning service via the partner organised, contact the key account manager.

  • From the merchants processing over 6 million operations annually (Level 1)—the Attestation of Compliance, AOC.
  • From the merchants processing to 6 million operations annually (Levels 2, 3, and 4)—the Self-Assessment Questionnaire, SAQ.

    With questions on completing the questionnaire, contact the ECommPay key account manager.

After all required documents have been checked, the merchant can start processing card payments—the merchant is informed about this (as well as about the expiration of the documents validity period) by the ECommPay key account manager.

In the case of other payment systems, the PCI DSS compliance documents usually should be provided directly to these payment systems, however, the merchants can consult with the key account manager about the necessity of providing these documents to ECommPay.

Figure: What are the differences between test and production environments?

As a rule, during the integration process, merchants get access first to the test environment to try essential workflows without processing real payments, then to the production environment in order to deploy customised and tested solutions.

For these purposes, the ECommPay technical support specialists create and configure two projects of interaction with the merchants' web services—a test project and a production project—with specific identifiers for each of them (project_id). Changing a project ID in requests turns the test environment into the real one. Since sets of parameters and addresses for receiving requests in the two environments are identical, it is important not to confuse the project IDs and handle them properly. By default, the technical support specialists provide merchants with a single test project, but it is possible to create additional projects on request.

Note that the test environment has a limited number of available payment methods and scenarios. For more information, see the corresponding sections on testing via direct use of payment cards (Test cards) and alternative payment methods (for example, testing a QIWI wallet).

All test payments are processed in the platform like the ones in the production environment: they are registered in the platform with the information about them displayed in the Dashboard interface, and the details of payment instruments are processed and protected without actual debiting taking place. Therefore, testing provides you with a complete picture of the work process when you can use real data of payment cards, wallets, and other instruments without running risks of payment information misuse.

The environment in each of these cases can be defined as a set of internal software components in the platform that emulate payments in test mode and actually process payments in production mode.

Figure: What are the URLs for sending requests?

Each of the ECommPay payment platform interfaces uses its own base URL.

This is important to keep in mind, for example, when you use Payment Page and Gate for different actions: you can generate a token via Payment Page and then make a payout with this token via Gate. In this case, you use two different URLs: https://paymentpage.ecommpay.com and https://api.ecommpay.com for Payment Page and Gate respectively. To request balance information about this payout via Data API, you can use the third base URL: https://data.ecommpay.com/v1. Even with such an abundance of URLs, we still hope you find it quite comprehensible.

Information about the base URLs, request structures, and other features of the interfaces is provided in sections with the descriptions of these interfaces. The URLs for program and customer actions are listed below:

  • https://api.ecommpay.com is for interaction via Gate. For example, the URL for a payment status request is https://api.ecommpay.com/v2/payment/status. For more information about working with the Gate API requests, see Request format.
  • https://paymentpage.ecommpay.com is for interaction via Payment Page. For example, a GET payment request is GET /payment?payment_currency=EUR&project_id=42&payment_amount=1000&... HTTP/1.1 Host: https://paymentpage.ecommpay.com. For more information about working with the Payment Page API requests, see Request format.
  • https://data.ecommpay.com/v1 is for interaction via Data API. For example, the URL for an account balances request is https://data.ecommpay.com/v1/balance/get. For more information about working with the Data API requests, see Using Data API.
  • dashboard.ecommpay.com is for merchant employees to access the Dashboard web interface.

Figure: What are the differences between payment and operation?

Payment within the platform is a comprehensive record of one settlement between a merchant and a customer. A single payment may include a one-time cash flow—from the customer to the merchant (purchase) or vice versa (payout)—or a repeated cash flow—for example, a purchase followed by a refund or a series of debiting payments. The payment is considered completed upon settlement between the merchant and the customer as part of the service provided by the merchant (which includes the corresponding payment request initiated by the merchant). Like in everyday life, the purchase can change its final state—it can be completed with the status of success and subsequently get the status of partially refunded.

Operation within the platform is a single action with funds performed during a payment. An operation can include placing a hold on funds for their consequent debiting, the debiting itself, refund, or payout. Processing a single payment may require one or more operations. Such a division is helpful in terms of controlling settlements at the level of payments and specific operations.

Each payment in the platform has its identifier (payment_id) that is unique within a project. Such IDs can include numbers, Latin letters, and other characters in the UTF-8 encoding, and their length must not exceed 255 characters—for example, payment-123 or cosmoshop.sale_456. If a request is valid, the payment is registered in the platform and the appropriate operation is initiated for this payment. Each operation gets an identifier (operation_id) that is unique within the platform. These IDs are passed in callbacks, and you can use them in the Dashboard interface.

Note that a payment and the operations within the payment can have different statuses. For example, a payment with the refunded status includes the refund operation with the success status. For more information about the differences and features of these concepts, see Payment models and statuses.

Figure: What are the differences between purchase, refund, and payout?

  • Purchase is a payment with a transfer of money from a customer to a merchant. It can include payments for goods and services, booking or reservation prepayments, subscription payments, and so on. A purchase can be a one-time or recurring payment, and it can also be refunded in certain cases.
  • Refund is the operation of returning the money from a merchant to a customer after a purchase. This can refer to cancelling reservations or returning goods. Along with that, refunds can be full (the customer gets the entire amount) and partial (the customer gets a part of the previously paid amount).
  • Payout is a payment with a transfer of money from a merchant to a customer. This can refer to receiving prize money, bonuses, or compensation for expenses.

Purchases can be made using all interfaces of the platform. Payouts and refunds are initiated through the Gate API and Dashboard. While these features are supported for the card payment methods, some of them may be unavailable for alternative payment methods. For up-to-date information about individual payment methods, see their descriptions in the corresponding sections.

Figure: What are the differences between one-step and two-step purchases?

In short, the choice between one-step or two-step purchases depends on how quickly funds are debited and how quickly and easily they can be partially or fully returned after a payment is made.

A one-step purchase implies debiting funds without delay—as quickly as it is done in the payment systems. This is a good option when it comes to paying for goods or actually provided services and the amount of payment is fixed and can not be changed. To return the funds to the customer upon completing a one-step purchase, you need to issue a full or partial refund. One-step purchases are supported for different payment methods and can be used for loan repayment to microfinance organisations. For more information about this type of payment, see One-step purchase.

A two-step purchase includes two stages: placing a hold on funds, and after confirmation, debiting or returning them to the customer. The total amount of money that is to be eventually debited or returned can change from the previously held amount. This is a good option for different types of booking and renting services, services with prepayments and insurance premiums, and others. In such cases, the held funds can be debited upon the merchant's confirmation request or after a specified period of time. If the funds have not been debited, you can return them to the customer by releasing the hold on funds. If the funds have been debited, you can issue a refund (the same way it is done with one-step purchases). Two-step purchases are currently supported only for payment cards. For more information about this type of payment, see Two-step purchase.

You can always consult with the ECommPay key account managers on choosing the most suitable option for your business sphere in particular regions.

Figure: What are the differences between payment methods?

Payment methods within the ECommPay platform are ways of making payments characterised by supported operations, currencies, payment instruments, and user scenarios. The availability of these methods varies on a regional basis. For example, purchases made in Indonesian rupiah through online banking systems and purchases in the same currency in local convenience stores are two different payment methods. Thus, such characteristics specific to different regions and business spheres give relevance to the plethora of payment methods available within the platform. The ECommPay key account managers can provide you with deeper insights into specific payment methods and differences between them and help you select methods most suitable for your business activities.


Figure: Why do I need different sets of required parameters in requests?

The payment platform allows you to perform a wide range of operations with the use of different payment methods. These operations may require participation of different partners (payment systems and providers) with their own processing workflows and requirements for payment parameters. Therefore, such parameters as payment description, a customer's phone number or email address, and others can be mandatory or optional in different cases.

We strive to ensure the maximum availability of payments and operations within the platform by reducing the number of required parameters on a case-by-case basis and specify which parameters are required and which are optional in API specifications and documentation. Along with that, there may be instances when the same parameters can be either mandatory or optional for a single operation within one payment method depending on specific factors (for example, in case of the AVS check). In such complex situations, we adopt a special procedure of submitting additional information when the payment is performed.

To optimise the work with mandatory and optional parameters, you can set up registration and use of the most complete set of data about customers in each request since this information is often required as additional parameters by providers and payment systems. If you have any specific questions about working with parameters, contact the ECommPay technical support specialists.

Figure: Why do I have to specify a payment method when opening Payment Page?

The Payment Page payment form opens by default after the customer selects a payment method on the payment method selection page:

However, this functionality may not always be relevant. This maybe the case when the customer selects a payment method before opening Payment Page, or when they need a specific payment method for payment operations in a particular region. In such cases, requests for opening Payment Page contain the force_payment_method parameter which opens the Payment Page form with a preselected payment method. As a rule, it is the form where the customer enters payment information and other requested details and confirms the payment operation:

This is useful in terms of improving customer scenarios. Note, however, that preselecting payment method makes it impossible for the customer to change the method in Payment Page. Thus, preselecting payment method should be implemented only if this specific payment method is relevant for the customer. For more information about this functionality, see Preselecting payment methods.

Along with that, there are other features that can be useful for optimising customer scenarios and use of payment methods—for example, limiting the list of payment methods (using the hide parameter) and initialising payments with payment card tokens.

Figure: Why is it important to pass the customer ID and IP address?

Customer IP address and ID are among the required parameters for performing financial operations within the ECommPay payment platform. These parameters are necessary when operations are analysed for fraud. With this data omitted or incorrect, operations may be rejected, which results in a decreased conversion rate.

Figure: What is the correct way to specify customers' first and last names?

Requests to the payment platform may require specifying the first and last names of a customer and/or a cardholder. These parameters are checked not only for correctness of the data format but also according to different rules including fraud prevention rules. Thus, it is important to meet a number of conditions for forming requests. For example, the payment platform does not allow merchants to issue payouts to non-personalised payment cards. Such payments are rejected since it is impossible to check them for sanction restrictions. Moreover, payment systems may check whether the customer's first and last names are specified correctly in accordance with their rules.

For correct processing of payments and preventing declines due to errors with first and last names specified, there are the following recommendations:

  • use real first and last names (for example, specifying CARDHOLDER NAME or Customer Name is incorrect);
  • make sure that each parameter contains at least 2 characters and, if possible, not more than 50 characters;
  • it is possible to use letters, numbers, and other characters in the UTF-8 encoding.

The following additional restrictions apply to the card_holder parameter:

  • it is possible to use:
    • Latin letters without diacritics;
    • Cyrillic letters;
    • periods in abbreviations (for example, Mr. or Jr.);
    • apostrophe (for example, d'Arc or O'Hara);
    • hyphens in compound names (for example, Anna-Maria or Jean-Baptiste);
  • make sure there are no hyphens for abbreviations and contractions—they are considered as word separators. For example, specifying M-r Holder is incorrect since this construction contains three words with two words consisting of a single letter;
  • make sure the value contains at least two words and no more than one period. For example, specifying Alexandre Dumas Jr. is possible, while Mr. Alexandre Dumas Jr. is incorrect.

Figure: What is the correct way to specify phone numbers?

Since all payment providers have their own rules of accepting and processing phone numbers, you may come across some issues when working with requests—for example, whether a number must begin with “+” or “0” and whether it should contain a country code, brackets, or dashes.

These difficulties are eliminated through processing phone numbers in the platform—when a number with a country code is sent to the platform, it is processed and, if necessary, transformed into the format accepted by the provider. You can specify phone numbers in various formats with a plus, hyphen, and other characters. However, it is recommended that you only use digits because all phone numbers eventually have this format within the platform—a number must be from 4 to 24 digits long without spaces and punctuation marks, for example, 9012345678, 79012345678, 0447307418560, 380671381116, 254712539238.

If a customer is required to enter a phone number through Payment Page when making a payment, there is a form with hints and validation of entered values to prevent format errors.

However, particular payment methods may have special requirements concerning formats of phone numbers. For more information, see Payments by using alternative methods.

Figure: What can be specified in the payment description?

Payment requests contain the description parameter that can be mandatory (for example, with refunds) or optional depending on a payment method and type of operation. If you want to know in what cases this parameter is required, see the sections with the descriptions of payment methods.
  • If description is mandatory, its value must contain an explanation for the operation—for example, Partially refunded due to partially returned order (wrong size), Fully refunded due to technical issues with the service, or The full cost of the ticket is refunded due to the session cancellation.
  • If description is optional, its value can contain any additional information about the payment - for example, Funding wallet 007, Crediting account 271828, Payment with a promotion code or Withdrawal of funds on request #314.

If descriptions are provided in requests, they are used in callbacks, displayed in the Dashboard interface, and can be helpful for merchants in payment analysis.


Figure: What are the parameters of callbacks?

Callbacks sent from the ECommPay payment platform to merchants' web services include sets of parameters with information about a payment and the last operation performed within this payment. For more information about standard sets of parameters, see Callbacks. Along with that, the structures of callbacks can be configured according to merchants' preferences provided that it is coordinated by the ECommPay technical support specialists. Viewing and changing callback settings is possible only upon request to the ECommPay technical support specialists.

Figure: Why don't I receive callbacks?

If a callback is not received over the specified period of time, check the following settings:

  1. The callback URL is the URL provided to the ECommPay specialists during integration.
  2. The URL is configured correctly to accept HTTP requests from the payment platform—The ECommPay IP addresses are in the whitelist and are not blocked by the firewall or other network devices.
  3. The payment request enables the function for sending callbacks—that is to say, it does not contain the parameter callback.force_disable with value 1.

If this does not help, and callbacks are still not received, contact the ECommPay technical support specialists. Make sure you provide the project ID and the corresponding callback URL.


Figure: How do I check the status of a payment or an operation?

For these purposes, you can use the Dashboard interface and program messages—callbacks and responses sent to payment status requests.

The Dashboard interface have registers and payment information tabs which display the statuses of payments. For more information, see Monitoring payment processing. Note that it takes several minutes for the payment data to appear on the Dashboard interface.

Program messages contain payment statuses in the parameters status, code, and message of the payment and operation objects and the errors array. In this case, the information is updated alongside with the processes of messages generation and transmission. For more information, see Callbacks and Checking current payment information.

Figure: Why is there no funds transfer with the response to the request having the success status?

When it comes to working with the Gate interface, keep in mind that synchronous responses sent to requests processed according to the asynchronous model of interaction use the status parameter in the body to indicate the status of a request, not a payment or operation. The success status in the request body indicates that the request has been accepted for processing, while the error status means that it is impossible to process and execute the request. For more information about these statuses, responses, and their general structure, see the Response format.

In order to get the information about the statuses of payments and operations, see the status parameter in the corresponding objects payment and operation in callbacks and responses to payment status requests or use Dashboard. For more information about payment and operation results, see How do I check the status of a payment or an operation?.

In some cases, the actual transfer of funds on the side of payment systems can be carried out with a delay (up to several days) after the operation is confirmed and receives its final status. Thus, if you have questions about discrepancies between flow of funds and the status of a payment or operation, consult the ECommPay technical support specialists or contact the providers and payment systems to get the status of a specific payment.

Figure: Why was the operation rejected?

If there are errors or rejections during request processing or operation performing, you can learn the reason:

  • in a synchronous response to a request—in case of an error during the initial request processing. For more information about these errors, see the Response format section.
  • in an intermediate or final callback—through a response code and a message which are passed:
    • in the errors array—if the operation was rejected in the payment platform (for example, it failed the established business rules validation);
    • in the operation.code and operation.message parameters—if the operation was rejected by a provider or payment system.

    For more information about working with callbacks, see Callbacks.

  • in the payment information tabs in the Dashboard interface. For more information about working with registers and payment information tabs, see the Monitoring payment processing section.

For more information about possible errors during operation processing and the codes which are passed in callbacks and displayed in the Dashboard interface, see Information of operations performing.