Payments

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, 13125555251, 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.

Figure: What can be specified in the payment description?

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.