Payments

The payment platform allows you to perform a wide range of operations with the use of different payment methods. These operationsOperations with the use of different payment methods 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.

The Payment Page payment form opens by default after the customer selects a payment method on the payment method selection 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 when opening Payment Page with a particular method preselected, the customer is restricted in selecting another payment method even in cases when the first payment attempt failed and retry attempts can be used (details). Thus, preselecting a payment method should be implemented only when it is certain that this specific method is relevant for the customer and this capability can be used in combination with other ones, including the capability of payment retries. More information about preselecting payment methods is provided in a separate article.

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.

Customer IP address and identifier are required for processing financial operations in the ecommpay platform and needed for analysing the operations for fraud. That is why, if this data is omitted or incorrect, operations can be declined.Customer IP address and identifier 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.

When specifying the first and last names of a customer and/or a cardholder, it is important to meet a number of conditions for forming requests, since these parameters are checked not only for correctness of the data format but also according to different rules including fraud prevention rules.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, an apostrophe, hyphens in compound names:
  • Latin letters without diacritics;
  • Cyrillic letters;
  • periods in abbreviations (for example, Mr. or Jr.);
  • an apostrophe (for example, d'Arc or O'Hara);
  • hyphens in compound names (for example, Anna-Maria or Jean-Baptiste).
• Ensure that 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.
• Ensure that there are no hyphens for abbreviations and contractions because hyphens are considered as word separators (or example, specifying M-r Holder is incorrect). For example, specifying M-r Holder is incorrect since this construction contains three words with two words consisting of a single letter.

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.Generally, a phone number must be specified in full, with the country code, although in certain cases (such as card payments) the country code is not required. Besides, if no additional restrictions are applied within the project and the payment method in use, you can specify phone numbers in various formats, for example, using a plus, hyphen, and other characters, and this number will be processed so that it can be accepted by the payment provider. However, it is recommended that you use from 4 to 24 digits without spaces and punctuation marks because all phone numbers eventually have this format within the platform (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 Methods.

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.

Every financial operation entails the transfer of funds from a specific ‘source’ to a designated ‘recipient’ through a connecting ‘channel’. In case of the ecommpay payment platform, these are defined as follows:

• The source and the recipient are the customer's payment instrument and the funds of the merchant's balance, respectively (for purchases, this correlation works as specified, while for refunds, it works in reverse).
• The payment channel is a combination of technical means and logical entities that facilitate the transfer of funds between the payment platform serving the merchant and the payment service serving the customer.

When the currency of the customer's payment instrument, the merchant's balance currency, and the payment channel currency are the same, financial operations can be processed without the need for conversion. However, when at least one of the currencies differs from the others, conversion becomes necessary to enable the transfer of funds through the channel in use.

The currency of the channel is considered the actual currency of the operation, also known as the operational or settlement currency (this can be important for payment accounting, payment analysis, chargebacks resolution, and other related processes). Thus, the conversion process is structured as follows:

• If the currency of the customer's payment instrument differs from the settlement currency, then, to process a payment via the channel, conversion is performed on the side of the organisation that serves this payment instrument.
• If the currency of the merchant's balance differs from the settlement currency, then, to process a payment via the channel, conversion is performed on the ecommpay side.

An example scenario would be a Polish customer making a payment in Norwegian krone (NOK) through a payment channel for a service in Norway, using a card denominated in Polish zloty (PLN), while the merchant's balance currency is the euro (EUR). In this case, the conversion from zloty to krone is performed on the issuer's side (at the rate and terms applied by them), and the conversion from krone to euro is performed on the ecommpay side.

Additionally, there are scenarios where the initial currency of an operation, as specified in the request, is different from the channel currency. To handle such situations, the payment platform uses an algorithm where the initial amount is converted into the channel currency and the operation is subsequently processed with the converted amount in the channel currency (additional secondary conversions, as in the provided example, can be applied if relevant). Along with that, in the standard program callback about the operation processing, the initial amount and currency, submitted in the request, are specified as sum_initial, while the converted settlement amount and currency are specified as sum_converted.

In summary, currency conversion during the processing of financial operations is applied as an auxiliary procedure to adjust to the payment channels in use, both on the side of the customer and their payment service and on the side of the merchant and the ecommpay payment platform.

In today's e-commerce landscape, abundant with various payment methods, instruments, and currencies, currency conversion plays a crucial role in enabling seamless operation processing and service delivery. However, both customers and merchants are averse to incurring losses through fees and exchange rate differences during conversion.

To minimise the need for conversions and potential losses, merchants can adopt a comprehensive approach in this direction.

• Key to this strategy is analysing the audience and their payment preferences, including their geographical locations, favoured payment methods and currencies, as well as their frequency of encountering currency conversions.
• Aligning the spectrum of payment methods and channels with the audience's specifics and the merchant's business development goals is also essential. Collaborating with the ecommpay account manager can help to optimise the structure of supported currencies, balances, and channels. This may involve setting default currencies for automatic conversions and implementing other advantageous solutions.
• Providing users with the option to select their currency can prevent unnecessary conversions (details). In case of working with the payment form Payment Page, you can have this capability set up in the form (details). In other cases, such capability can be set up on the web service side.
• Facing other issues or challenges related to conversion, you can also contact the ecommpay specialists—we are always committed to delivering the best service and solving even the most unconventional problems.

The meaning of the term ‘refund’ in the payment platform. In the ecommpay payment platform, a refund is an operation of reimbursing a customer for the amount withdrawn from their account for a purchase. In other words, if funds have been taken from a customer during the processing of a payment via the platform, you can make a refund via the platform to return the funds to the customer within the same purchase.

All of this is quite straightforward, but let us dig deeper to understand different aspects.

Insights into refunds. What you need to know to get a better understanding about working with refunds:

• Refunds can be full and partial (for returning either full or partial amount of the purchase).
  In the platform, it is possible to issue multiple refunds for a single purchase provided that the amount of each subsequent refund does not exceed the actual payment amount amount that was debited for a purchase and has not been returned to the customer yet with the previous refunds (this amount is called the actual payment amount).

• Refunds can be unavailable in some cases.
  While refunding card payments is usually available without restrictions, in case of alternative payment methods the situation can be different: depending on the method, refunds can be supported in full or with restrictions, or not supported at all. For example, issuing partial refunds can be unavailable, or you may be unable to issue any refunds if a time limitation is set for how long a purchase can be refunded after it was completed.
  What can be done about it? First of all, you can obtain the information whether refunds are supported for each payment method being set up and whether there are any special aspects to be considered in case of refunds. Besides, if refunds are unavailable but the return of funds is needed, you can get the information whether there are other ways to reimburse customers (for example, by issuing payouts with the use of the same or other payment methods). In these and other complicated situations, you can be assisted by your ecommpay account manager.

• Refunds can be issued with the use of different technical operations.
  Depending on the specifics of various payment systems, the technical operation for returning funds can be either reversal or refund. Normally, the reversal operation is used when a refund is made within the operation day on which the corresponding card payment has been processed and the refund operation is used in other cases. Along with that, the reversal operation can be used, for example, when it is confirmed (via the payment confirmation operation) that the funds have not been transferred to the customer's account.
  What can be done about it? Keep in mind that such aspects can be encountered and do not get alarmed when you come across different names of operations. Speaking of the operations' names, all refunds in the Dashboard interface are marked as refund operations (for the sake of simplicity). If you need to know what operation, reversal or refund, was actually used for a refund, use program callbacks and, if relevant, Data API.

For more detailed information, refer to the article Purchase refunds.

Ways to initiate refunds. On the merchant's side, refunds can be initiated via the Gate API and Dashboard.

When working via the Gate API, to initiate refunds, use the endpoints and formats described in the corresponding articles: for payments with the direct use of cards, the information is provided in the Purchase refunds article; for payments with the alternative methods, the information is provided in the articles about working with these methods in the Methods section Purchase refunds article and in the articles of the Methods section.

When working via Dashboard, use the tools for issuing single and mass refunds described in the corresponding article.

Other ways to return funds. Such ways surely exist. In some cases, instead of usual purchases with the subsequent refunds, two-step purchases can be useful. As a rule, within each two-step purchase, a particular amount is first authorised on the customer's account, and then either only a part of this amount is withdrawn, while the other part is released, or nothing is withdrawn and the funds are fully returned to the customer. Along with that, a significant advantage can be the promptness of the funds' return: that is, a release of funds can take seconds or minutes, while an actual refund can take hours or even days.

Besides, in situations when it is required to return funds but refunds are not supported for payment methods in use or cannot be issued due to imposed limitations (for example, when the refund option is time-restricted for a certain purchase), you can coordinate with customers and the ecommpay specialists the processing of corresponding payouts via the payment methods in question or via other payment methods. In such cases, it is important to inform your customers about the indirect return of funds and obtain their consent to reimbursements via payouts. At the same time, the capability of returning funds via payouts can work as a competitive advantage and foster customers' loyalty.

Finally, if you come across any other refund-related situations which are not covered in this answer or in the articles mentioned in this answer, you can contact your account manager and mutually search for best solutions, which you will surely find.

Overview

Occasionally, due to various circumstances, it may be necessary to reverse funds after transferring them as part of a refund or payout—for example, if the refund was made for the wrong purchase or if the payout was made for an excessive amount. The ecommpay payment platform provides such capabilities for cancelling such actions, but only within the limitations imposed by providers and payment systems.

Conditions

• Refunds and payouts can be reversed only within the payment methods that support this capability, taking into consideration any additional restrictions on payment instruments and other criteria.
  Additional information about such restrictions for card payments is provided in this answer. Information for alternative payment methods can be clarified with the ecommpay technical support specialists.

• When considering time restrictions imposed by providers and payment systems, it is also necessary to consider the time required to reverse a refund or a payout on the ecommpay side—typically, this process takes no more than thirty minutes.
  Reversing operations after the specified deadlines may lead to chargebacks, and in such cases, the merchant is responsible for any potential compensation.

• Refunds and payouts can be reversed only in relation to those operations and payments that are not disputed by customers.
  Upon receiving information about chargebacks of incorrectly performed refunds or payouts, it is advisable to accept such chargebacks. For more informations on handling chargebacks, refer to the relevant FAQ subsection.

• You can reverse only separate refund operations.
  The reversal operations can not be cancelled. Also, it is not possible to reverse several refund operations with partial refunds for a single purchase at once. Partial refunds, like full ones, can only be reversed individually.

• Refunds issued for card payments can be reversed only for cards of particular card networks, with consideration to the specified time limits:
  • for the American Express cards—within the time period relevant for a particular project (this period can be clarified with the ecommpay account manager);
  • for the Mastercard cards—within 24 hours;
  • for the Visa cards—within 30 calendar days.
• Card payouts can be reversed only for Visa cards, within one calendar day, and only in exceptional cases established and regulated by the card network.

Reversal procedure

To reverse a refund or a payout, proceed as follows:

1. Find the identifier of the operation (operation_id) you need to reverse and inform the ecommpay technical support specialists that a reversal is needed.
   To find the operation identifier, you can use the payment information tab in the Dashboard interface or a program callback with information about the operation completion. To contact technical support, you can use the Dashboard interface (with the function Create ticket to Support in the payment information tab), the Telegram support bot (with the function Get extra information from support available after searching for payment and operation details) or email (support@ecommpay.com).

2. Receive the confirmation that the reversal request has been registered on the ecommpay side.
   Each request is automatically registered and assigned an identifier (ticket ID), which is communicated in the communication email and can be referenced for further inquiries about the request and its progress.

3. Receive a response regarding the outcome of your request.
   Processing such requests typically takes up to 30 minutes within which the ecommpay support specialists perform the following:

   1. Verify that the target operation is eligible for a reversal according to the card network's rules.

   2. If the reversal eligibility is confirmed, perform the necessary actions.
      For reversing a refund—the refund_reversal operation is created and processed as part of the payment for which the refund was made, this operation is assigned the success status, while the payment is assigned the partially refunded or success status (depending on the actual payment amount that remains); the status of the refund operation being reversed remains unchanged, and the information about the created operation is displayed in the payment information tab in the Dashboard interface without being sent in program callbacks to the web service.
      For reversing a payout—this payout is assigned the decline status, with no additional operations created, the payment information is updated in the Dashboard interface, while the callback with information about the change of the payout status is sent to web service by prior agreement with the merchant.

   3. Communicate the result regarding the outcome of the reversal request.

4. If the target operation has been reversed, ensure the return of funds.
   After reversing a refund, the balance should increase by the refund amount minus the fee charged by ecommpay for the reversal, while after reversing a payout, the balance should increase by the payout amount and the fee charged previously by ecommpay for processing the payout.