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 technical support specialists support@ecommpay.com.

Integration with the platform

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 in the platform, and information about them is displayed in the Dashboard Light(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 — for their actual implementation. That's all :)

Figure: Where requests should be sent?

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 PP 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/v1/balance/get . For more information about working with requests of Data API, see Using Data APIRequest format.
  • dashboard.ecommpay.com for merchant employees to access the Dashboard web interface.
  • dash-light.ecommpay.com for merchant employees to access the Dashboard Light web interface.

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.

Payments performing

Figure: Why should the payment method be specified when Payment Page opening?

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

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 (Additional payment information submission).

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.

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.

Figure: Why there is no callback?

If the callback does 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 status of a payment or operation can be found out?

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

In the Dashboard Light and Dashboardinterfaces information about payments state is displayed in the registers and payment cards, (for more information, see the sections Monitoring payment processing for Dashboard Light and Payments for 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 does the payment have the Success status, 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 Light(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 the operation was rejected?

If errors during request processing or operation performing occurs, 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 Light(Dashboard) interface. For more information about working with registers and payment cards, see Monitoring payment processing(Dashboard Light) and Payments(Dashboard).

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