This section provides answers to frequently asked questions from technical specialists about working with the ECommPay payment platform.

These questions are divided into the following groups:
  • Integration with the platform is about connecting to the platform and configuring and testing various functionalities.
  • Payments performing is about different types of payments, operations and procedures performing.
  • Callbacks receiving is about working with callbacks from the payment platform.
  • Results monitoring is about controlling and interpreting the results of various payments, operations, and procedures performed in the platform.
If the information provided in this and other sections of the documentation is not enough to solve your problems, contact our specialists:
  • with business and financial issues (about the cost of services, calculating commissions, working with balance sheets, and so on) — to the key account manager
  • with technical issues (about working with different interfaces, making requests, and so on) to the technical support specialists (support@ecommpay.com)

Integration with the platform

Figure: What is PCI DSS for?

Payment Card Industry Data Security Standard (PCI DSS) — this is a standard for the proper protection of payment card holder data. It is developed by the PCI Security Standards Council and sets requirements for all organizations that have to process, store, or transmit payment card data. A merchant cannot perform payments using payment cards without compliance with PCI DSS requirements.

If the merchant has the PCI DSS compliance certificate, they can provide a copy of the certificate and organize the work in any way, including storing card data on its side and transmitting this data in requests in unencrypted form. If the merchant's company is not PCI DSS-compliant, they should complete Self-Assessment Questionnaire and may consult the key account manager, if they need any assistance in completing the questionnaire. After that they can store data on the payment platform side and perform purchases using the ECommPay payment form and payouts using card tokens (for more information about tokens, see the section Using tokens)

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

Usually, when integrating to the payment platform, the merchant is granted access to the test environment first, and then to the production one, to test the main scenarios of working without making real payments and bring out customized and proven solutions.

To do this, the ECommPay technical support specialists create and configure two interaction projects with the connected web service in the platform: a test project and a work project, with a specific ID for each of them. When this identifier (project_id) is changed in requests — everything that is tested turns into the real one. Both the addresses for receiving requests and the parameter sets are identical in the test and production environments, that is why it is important not to confuse project IDs and handle them properly.

By default, only one test project is created, but if necessary, you can request additional projects from technical support. The test environment has a limited number of payment methods and scenarios. For more information, see the relevant sections on testing for direct use of payment cards (Test cards) and when working with alternative payment methods (for example, testing a QIWI wallet).

All test payments, as well as real ones, are registered with the platform, and information about them is displayed in the Dashboard (Old Dashboard) interface, and the payment instrument details used during testing are processed and protected, just like real ones, but no real debits are made. Therefore, when testing, you can get a full understanding of how to work with payments and not be afraid to use different data, including data from real payment cards, wallets, and other instruments.

And what is the environment in each of these cases? This is a set of internal software components of the platform, which in one case are configured to emulate payment processes, and in the other—to actually perform the processes. That's it :)

Figure: Where to send requests?

The ECommPay payment platform is designed in such a way that each of its interfaces uses its own base URL.

This is important to keep in mind when, for example, Payment Page is used for some actions, and Gate — for others. For example, to generate a token by using Payment Page and make a payout by this token by using Gate, two requests to two different URLs are sent: https://paymentpage.ecommpay.com and https://api.ecommpay.com. And to get information about the balance of funds after this payout by using Data API, send a request to the third address: https://data.ecommpay.com. This excess of addresses may cause confusion, of course, but we still believe that it is quite amenable to comprehend :)

Information about the base URLs, requests structures, and other features of each of our platform's interfaces is provided in the description of working with these interfaces, and the full list of URLs for program and customer actions is provided below:

  • https://api.ecommpay.com for interaction via Gate. For example, the URL for requesting a payment status looks like https://api.ecommpay.com/v2/payment/status. For more information about working with requests of Gate API, see Request format.
  • https://paymentpage.ecommpay.com for interaction via Payment Page. For example, a GET request for making a payment looks like 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 requests of PP API, see Request format.
  • https://data.ecommpay.com for interaction via Data API. For example, the address for requesting account balances looks like https://data.ecommpay.com/balance/get. For more information about working with requests of Data API, see Using Data API and Request format.
  • old-dashboard.ecommpay.com for merchant employees to access the Old Dashboard web interface.
  • dashboard.ecommpay.com for merchant employees to access the Dashboard web interface.

Figure: What are the differences between payment and operation?

Payment in terms of the platform is a complete story of one settlement between the merchant and the customer. In the framework of a single payment may occur as a single cash flow (from customer to merchant when performing purchase, or in the opposite direction when performing payout) and repeated (for example, when making purchase followed by refund or by recurring payments in one purchase). Payment is considered completed when the settlement between merchant and a customer as part of the services (as well as the corresponding application from the merchant for payment performing) is completed. And, as in life, payment can change its final state: for example, the payment can be completed with success, and after some time become partially refunded.

Operation in terms of the platform is a single action with funds within the framework of making a payment. This can be, in particular, the holding of funds for their subsequent withdrawal, the withdrawal itself, refund or payout. For a single payment one or many operations may be required taking into account its specifics, but in any case, this splitting helps to control settlements at the level of whole stories-payments and specific actions-operations.

For each payment in the platform, its identifier (payment_id) is used, which is set by the merchant, transmitted in requests to the payment platform and uniquely identifies the payment within the project. Such identifiers can consist of digits, Latin letters, and other UTF-8 characters and must not exceed 255 characters: for example, payment-123 or cosmoshop.sale_456. When a correct request is received, the payment is registered in the platform and the operation for this payment is initiated. Each operation in the platform is assigned an identifier (operation_id) that is unique within the platform. These IDs are passed in callbacks and displayed in the Dashboard (Old Dashboard) interface.

Also one should keep in mind that the payment and operation may have different statuses, for example, a payment with the refunded status has the refund operation with the success status. Read more about the differences and features of these terms in the Payment models and statuses section.

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

Let's clarify:

  • Purchase is a payment with a transfer of money from a customer to a merchant. Purchase can be the paying for goods and services, prepayment for booking, payment by subscription, and so on. Purchases can be one-time or recurring. And they can also be refunded.
  • Refund is the operation of returning money from a merchant to a customer after the purchase has been made. A refund can be, for example, a cancellation of a reservation or a return of goods. Refunds can be for the entire payment amount (full) or for part of the amount (partial).
  • Payout is a payment with a transfer of money from a merchant to a customer. The payout can be the receipt of a prize, bonus or compensation for expenses, and so on.

Purchases can be made by using any of the interfaces available in the payment platform. Payouts and refunds in the payment platform are made via the Gate API and Dashboard (Old Dashboard). However, not all of these features may be supported by alternative payment methods, while all of them are fully supported by card methods. You can get relevant information about working with each of the methods in the section with its description.

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

To make a long story short, the differences are: how quickly funds are debited and how easily and quickly they can then be fully or partially returned to customers.

The point of a one-step purchase is that funds are debited without delay — at the same speed as it is done at the level of payment systems. This is convenient for paying for goods and services already provided, when the payment amount has already been determined and is not subject to change. If, after making such a purchase, you need to return the funds to the customer, this requires a full or partial refund. One-step purchases are supported when working with different payment methods and are used to repay loans in microfinance organizations, using the Analog Facility Terminal (AFT) payment acceptance channel. For more information about these purchases performing, see the section One-step purchase.

The point of a two-step purchase is that the funds is held first and later, upon confirmation, debited or returned to a customer — taking into account the total amount of provided services. This is convenient for different types of booking and renting, prepaid services and insurance premiums, and so on. In such cases, the held funds can be debited at the merchant's confirmation request or after the specified time is exceed. If you need to return funds to the customer, you can do this by canceling the hold before debiting, and after debiting — by returning them, as in cases with one-step purchases. Two-step purchases are currently supported only when working with payment cards. For more information about these purchases performing, see the section Two-step purchase.

For choosing the purchase type that is most suitable for a particular type of business in specific regions, you can always contact the ECommPay key account manager.

Figure: What are the differences between payment methods?

Payment methods in the ECommPay platform are means to make payments that are characterized by supported operations, currencies, payment instruments, and customer scenarios in the available for specific payment systems regions. For example, payment in Indonesian rupiah via online banking systems in Indonesia is one method, and payment in Indonesian stores in the same currency is another one. And these differences, which are specific to different regions and types of business, make it relevant for the payment platform to provide variety of payment methods. To clarify the differences between specific methods and help choosing the methods that are most suitable for the merchant's business type, refer to ECommPay key account manager.

Payments performing

Figure: Why do the sets of required parameters differ in different requests?

The payment platform allows you to perform many operations by using a variety of payment methods. These operations may require the participation of different partners (payment systems and providers), and each of these partners may apply their own rules for processing and requirements for payments parameters. Therefore, parameters such as payment description, customer's phone number or email address, and so on may be required in some cases and not required in others.

In the platform, we try to ensure maximum availability of payments and operations, so in each case we reduce the number of strictly required parameters to a minimum and describe it in the API specifications and documentation. Additionally, for complex situations where the same parameters may or may not be required for the same operation within the same payment method, taking into account specific factors (as, for example, in the case of checking AVS data), we apply a special procedure with payment additional information submission (Submission of additional payment information).

To optimize the work with mandatory and optional parameters, you can configure registration and use of the most complete set of customer data in each request (since these parameters can most often be requested by providers and payment systems as additional parameters). Also, if you have any specific questions about parameters and how to work with them, you can always contact ECommPay technical support specialists.

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

The Payment Page payment form opens by default from the payment method selection page:

But sometimes it can be excessive. For example, if the customer selects a payment method before opening the payment form, or if for some reason you need to provide a specific method that is preferred for payments from a specific region. For such cases, a Payment Page opening with a specific payment method is provided. And if you use the force_payment_method parameter in the request for opening, the payment form opens from the page for working with the selected method. This is usually a page for specifying payment details:

This is convenient and helps improve customer scenarios. However, when opening Payment Page with the specified method, the customer can no longer select another method. Therefore, you should open Payment Page with preselected method only if you are sure that exactly one payment method is relevant for the customer. For more information about working with this feature, see the section Preselecting payment method.

Additionally, to optimize customer scenarios and ways to work with payment methods, features such as limiting the list of payment methods (using the hide parameter) and payment by using payment card tokens (Payments by using tokens) can be useful.

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

When working with the ECommPay payment platform, the required parameters for performing financial operations include the customer IP address and ID. They are necessary for analyzing operations for fraud, and if this data is omitted or incorrectly specified, operations may be rejected, reducing the conversion rate.

Figure: How to specify customer name?

When forming requests to the payment platform, it may be relevant to specify the first and last names of a customer and/or a cardholder. And in such cases, it is important to comply with a number of conditions, because these parameters are checked not only for the correctness of the data format, but also for compliance with various rules, including the rules of protection against fraud. For example, the payment platform prohibits payouts to non-personalized payment cards, since they cannot be checked for sanctions restrictions, that is why such payouts are declined. In addition, the customer's first and last names can also be checked on the payment providers side for compliance with their rules.

In order to make payments correctly and prevent declines due to errors when entering names and surnames, it is important to follow the recommendations:

  • the first and last names must be real, for example, CARDHOLDER NAME or Customer Name are incorrect
  • the number of characters in the value of an individual parameter must be at least 2 and, if possible, not more than 50
  • letters, numbers and other characters in UTF-8 encoding are allowed

For the card_holder parameter, the following restrictions apply in addition to those that listed above:

  • it is allowed to use letters of the Latin alphabet without diacritics, letters of the Cyrillic alphabet, and:
    • period in abbreviations, such as in the words Mr. or Jr.
    • apostrophe, such as in d'Arc or O'Hara
    • dash in compound names and surnames, such as Anna-Maria or Jean-Baptiste
  • it is not allowed to use a dash for abbreviations, since it is interpreted as a separator between words, and therefore, for example, the construction of M-r Holder is incorrect, since it forms three words, two of which consist of only one letter
  • the value must contain at least two words and no more than one period, so, for example, the construction of Mr. Alexandre Dumas Jr. is incorrect, but Alexandre Dumas Jr. is acceptable

Figure: How to specify telephone number?

Due to the fact that each payment provider accepts and processes phone numbers according to its own rules, it may be difficult to specify a phone number in the requests accurately: whether to write “+” or “0” at the beginning, whether to specify the country code, whether to use brackets and dashes.

To avoid such difficulties, the payment platform supports the processing of phone numbers: it is enough to send a phone number with a country code, and this number will be processed in such a way that it will be accepted by the provider through which the payment is performed. In this case, you can use different formats, with a plus, dash, and other characters, but it is still recommended to use only digits (from 4 to 24 symbols, without spaces and punctuation marks: for example, 9012345678, 79012345678, 0447307418560, 380671381116, 254712539238), because all numbers are brought to this format in the framework of the platform.

If the number must be entered by the customer when paying via Payment Page, there is the form with hints and error protection in the format to help.

Figure: What can be specified in the payment description?

In the requests for making payments through the platform the description parameter can be used. Depending on the operation type and the payment method specifics, the parameter may be mandatory, for example, for refunds, and optional. Mandatory for different cases can be clarified in sections with descriptions of the methods that are used.
  • If the description parameter is required, its value must specify the reason for performing the operation, for example: Partial refund due to the fact that the customer returned part of the order (the size did not fit), Full refund due to technical problems with the provision of the service, or Refund of the full ticket amount due to the cancellation of the session.
  • If the description parameter is optional, its value may specify any additional information about the payment, for example: Replenishment of the wallet 007, Crediting to the account 271828, Payment by promo code or Withdrawal of funds on request No. 314.

If these descriptions are specified in requests, they are passed in the callbacks and displayed in the Dashboard (Old Dashboard) interface and, if necessary, can be used for additional analysis of payments on the merchant's side.

Callbacks receiving

Figure: What parameters are passed in Callbacks?

The structure of sent from the ECommPay payment platform to the merchant's web service includes sets of parameters about the last operation and the payment it relates to. Standard callbacks parameters set about financial operation and token generation are described in the section Callbacks. Still the callback structure can be configured based on the merchant's preferences on the request to the ECommPay technical support specialists. The merchant can view or change callbacks settings only upon request to the ECommPay technical support.

Figure: Why I receive no callback?

If the callback is not received within the specified time period, make sure that the following is true:

  1. Callbacks are expected at the URL that was specified to the ECommPay specialists when integrating.
  2. This URL is correctly configured to accept HTTP requests from the payment platform: ECommPay IP addresses are added to the white list and messages are not blocked at the level of the firewall or other network devices.
  3. The payment request does not disable the function for sending callbacks — the callback.force_disable parameter with the value 1 is not passed.

If all these conditions are met, but you still don't receive callbacks, you should contact ECommPay technical support by specifying the project ID and the URL where callbacks are expected.

Results monitoring

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

To do this, you can use both the user interface Dashboard (Old Dashboard) and program messages—callbacks sent in specified cases, and responses sent to request the payment status.

In the Dashboard and Old Dashboard interfaces information about payments state is displayed in the registers and payment cards, (for more information, see the sections Monitoring payment processing for Dashboard and Payments for Old Dashboard). Be aware that the delay in displaying payment data in the interface can be up to several minutes.

In program messages the information about payments state are passed in the status, code, and message parameters in the payment and operation objects and in the errors array (for more information, see the Callbacks and Checking current payment information sections). In this case the information is up-to-date in accordance with the speed of message generation and transmission.

Figure: Why there is the Success status in the response to the request, but the funds were not transferred?

When working with the Gate interface, keep in mind that in synchronous responses to requests, the status parameter in the response body indicates the status of the request, but not the payment or operation. The success status in the response indicates that the request was accepted for processing, and the decline status indicates that the request could not be accepted for processing and executed. And nothing else. Information about these statuses, its overall structure, and responses sending can be found in the section Response format.

To get information about the state of payments and operations, and not received requests, use the status parameters in the corresponding objects payment and operation in callbacks and responses sent to request the status of payments, or use the interface Dashboard (Old Dashboard). For more information, see the answer to the previous question.

At the end, it can be noted that in some cases, the actual funds transferring on the side of payment systems is carried out with a significant delay (up to several days) after the operation has been confirmed and received the final status. Therefore, if you have questions about discrepancies between the funds transferring and the statuses of payments and operations, you can contact the ECommPaytechnical support as well as specify the statuses of specific payments on the side of providers and payment systems.

Figure: Why my operation was rejected?

If you have encountered any errors when processing a request or performing an operation, the reasons of rejections can be found out in the following ways:

  • In a synchronous response to a request, if an error was detected during the initial processing of the request. For more information about these errors, see the section Response format.
  • In the received intermediate or final callback through the response code and message that can be submitted:
    • in the errors array, if the operation was rejected on the payment platform side, for example, if the operation did not pass the check for compliance with the established business rules;
    • in the operation.code and operation.message parameters, if the operation was rejected by the provider or payment system.

    For more information about working with callbacks, see the Callbacks section.

  • In the payment card in the Dashboard (Old Dashboard) interface. For more information about working with registers and payment cards, see Monitoring payment processing(Dashboard) and Payments(Old Dashboard).

For more information about possible errors during operations processing and the codes used in callbacks and the Dashboard (Old Dashboard) interface, see the section Information of operations performing.