Submission of additional payment information

General information

Mandatory parameters specified in the request for opening Payment Page usually provide enough information for payment processing. However, a payment system or a payment provider may require some additional data that otherwise is not required, this may be due to regional or country-specific requirements, additional fraud testing procedures or other conditions. Payment Page allows you handling such cases as it supports submission of additional payment information. In terms of this procedure, the customer is notified about the need to submit additional data, the required data is collected and the payment is processed considering the provided data.

In some cases, along with data provided in the request for opening Payment Page, a payment system or a payment provider may require some additional data. In such cases, the ecommpay provides the procedure submission of additional payment information. In terms of this procedure, the customer is notified about the need to submit additional data, the required data is collected and the payment is processed considering the provided data.

Submission of additional payment information does not require extra effort of the merchant, as the procedure is performed through interaction between the customer and the payment platform. Nevertheless, in order to avoid the need of submitting additional data, you can specify in the request for opening Payment Page data that may be required by payment systems or payment providers for processing payments, including optional parameters.

The requested data generally concerns the customer and their payment instrument, and for payments by using alternative payment methods it is the data provided in any optional parameters supported by Payment Page for initial request for payment processing. In order to avoid the need of submitting additional data, you can specify in the request for opening Payment Page data that may be required by payment systems or payment providers for processing payments, for example:

The information that the customer may be requested to provide may include the following:

  • customer_first_name—first name
  • customer_last_name—last name
  • customer_middle_name—middle name
  • customer_day_of_birth—birth date
  • customer_email—email address
  • customer_address—full address
  • customer_city—city of residence
  • customer_country—code of the country
  • customer_street—street of residence
  • customer_zip—postal code
Note: The final set of the requested data depends on the requirements of a particular provider or payment system and may vary. To precise the set of the data that may be requested depending on the payment method, you may contact your ecommpay key account manager.

Payment processing continues only after the customer specifies requested data and confirm the purchase. The following sections provide information about steps that the customer performs when submitting additional payment information.

Usage scenario

The basic usage scenario of submitting additional payment information can be described as follows:

  1. On the merchant web service side, the customer confirms the purchase of the order and is redirected to the payment form.

    If the option of time limit for using the payment form is enabled, the remaining time is also displayed on Payment Page.

  2. The customer enters the payment details.
  3. As the need for additional payment information is identified, a notification and additional fields for entering the data are displayed on Payment Page. The customer enters additional data, confirms the purchase and receives the result information.
Figure 1. 1 — Opening payment form


Figure 2. 2 — Entering payment details


Figure 3. 3 — Entering additional data


The workflow

The following diagram illustrated the procedure of submitting additional payment information.



  1. When the need for additional payment information is identified, the set of the data to be requested is formed in the payment platform and redirected to Payment Page.
  2. The page for entering the requested data is displayed to the customer.
  3. The customer enters the requested data.
  4. The data specified by the customer is transferred to the payment platform.
  5. The received data is processed in the payment platform, and after that payment processing continues in its ordinary way.

Usage specifics

When configuring time limit for using Payment Page, you should take into account that the time for submitting additional payment information is included in the common time for using the payment form. Hence, when you configure the time limit for using the payment form, you need to take into consideration the time of possible submission of additional data. If the restriction is not set, waiting time for submitting additional payment information is set by default, it is 30 minutes starting from the moment of identifying the need for additional data. In both cases, if the additional information is not provided before the remaining time expires, payment is automatically declined.

To monitor payments that involve submission of additional information, you can use notifications and information provided in the payment information tabs in Dashboard (for more information, see Monitoring and performing payments). Intermediate and final notifications sent from the payment platform contain the set of data requested from the customer in terms of submitting additional payment information. Intermediate notifications also contain the status of the payment (awaiting_clarification), which remain until the customer payment data is received.

The following is an example of a callback with the request of additional data (customer address) required for continuation of card payment processing.

Figure 4. Example of an intermediate callback
{
   "project_id": 1173,
   "payment": {
      "id": "15557465346",
      "type": "purchase",
      "status": "awaiting clarification",    // payment status
      "date": "2020-07-30T10:20:58+0000",
      "method": "card",
      "sum": {
         "amount": 131970,
         "currency": "USD"
      },
      "description": ""
   },
   "account": {
      "number": "431422******0056 ",
      "type": "visa",
      "card_holder": "JOHN DOE",
      "expiry_month": "01",
      "expiry_year": "2023"
   },
   "customer": {
      "id": "3b6d6827-8cdd-4040-aaf6-0a8f81b95c31"
   },
   "clarification_fields": {     // the requested data
      "avs_data": [
         "avs_address"
      ]
   },
   "operation": {
      "id": 72658000000461,
      "type": "sale",
      "status": "awaiting clarification",
      "date": "2020-07-30T10:20:58+0000",
      "created_date": "2020-07-30T10:20:58+0000",
      "request_id": "c0f65543b97c062cf172cf04df239ee16ae27b34-9b1943e6454385d28d4f975bfd397aef6aa55a71-00072659",
      "sum_initial": {
         "amount": 131970,
         "currency": "USD"
      },
      "sum_converted": {
         "amount": 131970,
         "currency": "USD"
      },
      "code": "9999",
      "message": "Awaiting processing",
      "eci": "00",
      "provider": {
         "id": 414,
         "payment_id": "",
         "endpoint_id": 414
      }
   },
   "signature": "oFcRanmZ5FrWt8zQWqHM15PPWKV5eAfIErQXBS/1uMwzF1..."
}