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.

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 all 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: for payments by using payment cards it is the data provided in the parameters of the avs_data object (for Address Verification Service (AVS) check) and the customer object, and for payments by using other payment methods it is the data provided in any optional parameters supported by Payment Page for initial request for payment processing.

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—patronymic or middle name
  • customer_day_of_birth—birth date
  • customer_email—email address
  • customer_address—address
  • customer_city—city
  • customer_country—country
  • customer_street—street
  • 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, contact your ECommPay key account manager.

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

Usage scenario

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

  1. The customer confirms the option to perform the targeted action, for instance to perform a purchase, and after that a loading page is displayed on Payment Page.

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



  2. As the need for additional payment information is identified, a notification and additional fields for entering the data are displayed on Payment Page. If the option of time limit for using the payment form is enabled, the new countdown starts at this step. For more information about special aspects of submitting additional information when the time limit for using the payment form is enabled, see the Usage specifics section.
  3. The customer enters the requested data and confirms continuation of payment processing.


The workflow

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

Figure: Interaction diagram



  1. When the need for additional payment information is identified, the set of the data to be requested is formed in the payment platform.
  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 not included in the common time for using the payment form. Hence, when you configure the time limit for using the payment form, you do not need to take into consideration the time of possible submission of additional data. 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. 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 Light (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 and the status of the payment (awaiting_clarification). The following is an example of a callback with the request of additional data (customer address) required for continuation of card payment processing.

Figure: Example of a 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":"424242******4242",
      "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..."
}