# Collecting customer data {#en_PP_Gathering_customer_data .concept}

An article about the capability of obtaining and using additional customer information during payment processing via Payment Page to minimise the need for auxiliary procedures.

## Overview {#section_ivk_bpf_gdb .section}

In some cases, along with data mandatory for payment processing, you may need to collect additional information from your customers, for example, their phone numbers or email addresses. Collecting such data can be useful as it allows merchants to:

-   Provide an extra layer of payment security by collecting and verifying customer information.
-   Improve user scenarios by avoiding the necessity to submit additional payment information \(when it is requested by payment providers,payment systems, and banks during payment processing—[learn more](en_pp_clarification.md)\).

The capability of collecting additional data is supported directly in the Payment Page payment form and, for certain payment methods, in the associated payment services \(such as Apple Pay, for example\).Keep in mind that collecting additional data increases the number of actions required from the customer to make a payment and can negatively affect the payment form conversion. Therefore, this capability should be used only when it is clearly necessary. In most cases, the optimal solution is to submit previously collected information about customers in the requests for opening Payment Page.

To work with additional data provided by customers on the payment formor in the third-party services, you can use payment information tabs in the Dashboard interface and final callbacks with the information about operation processing. To set up passing customer data in callbacks, contact the Ecommpay technical support.

## User scenarios {#section_wks_zfs_jsb .section}

A number of fields can be used to collect additional customer data on the payment form. These fields can be displayed at all times or only when necessary and can be required or optional. Along with that, the placement of these fields can differ: they can be located on the page where customers enter payment information or on the separate page that follows \(depending on the total number of fields\).

The way each field is displayed depends on its specific properties and what data is submitted in the request for opening Payment Page. The following display options are available for each of the additional fields:

-   `1`—the field is displayed with the prefilled value that was specified in the request. The customer can change this value.
-   `2`—the field is displayed and is left blank, but contains a name of the field.
-   `3`—the field is not displayed. The field value can be submitted to the payment platform only via a request.

![](images/ecommpay/en_pp_gathering_customer_data.svg "Additional fields display options")

The field display option is determined as follows.

|This parameter is required|+|+|+|+|–|–|–|–|
|This field must be displayed|+|+|–|–|+|+|–|–|
|The field value is passed in the request|+|–|+|–|+|–|+|–|
|**Field display option**|**`1`**|**`2`**|**`3`**|**`2`**|**`1`**|**`2`**|**`3`**|**`3`**|

To collect additional data via third-party services such as Apple Pay and Google Pay, the interfaces provided by these services are used. Depending on their specifics, requesting customer data may involve, for example, using information previously saved by the customer or other special features of interaction. Note that all requested details must be provided and data requests can be configured both via project-level properties and through individual request parameters. For instance, you can set collecting customer email addresses as a default via project properties and collect other types of data when necessary through request parameters \(learn more in the articles on payment methods [Apple Pay](pm_applepay.md) and [Google Pay](pm_googlepay.md)\). The data collected thereby can be sent to the merchant's web service in the payment result callbacks. To enable this functionality, contact the Ecommpay technical support specialists.

## Setup {#section_ts1_3sf_gdb .section}

To have the capability of collecting customer data enabled, you should:

1.  Decide which projectsand which payment methods supported for these projects may warrant the collection of additional customer data. For each case, determine what data needs to be requested and define the properties of the fields in question. Additional customer data may include a range of parameters \(to learn more, [see below](en_PP_Gathering_customer_data.md#section_jdb_1qx_tdb)\) while the properties of each field are the following:
    -   The field can be required or optional to fill in and/or display.
    -   It is a text or dropdown input field.

        To use a dropdown input field, for example, to collect *the name of the country*, you should provide the support specialists with all possible values for this list or coordinate and approve the use of definitions from the reference sources provided by Ecommpay.

    -   Its name: by default standard names are provided by Ecommpay; however, customisation is available.

        If you would like to add customised field names, provide the support specialists with the translations into all languages used for the project.

2.  Make sure that the technical support specialists have all the details about customer data to be collected as well as the information whether any of these parameters specified by customers on the payment form should be passed in final callbacks.
3.  Get notified by the Ecommpay specialists that the requested functionality has been enabled and test the work of the payment form with this capability if necessary.

## Collected data {#section_jdb_1qx_tdb .section}

The following parameters can be used for collecting customer data.

|Parameter|Description|
|---------|-----------|
|customer\_address  
 string

|The name of the street and the house number \(including any additional parts of the address such as building indicators and apartment numbers\) in the customer's address, separated by a comma.  
 A string, must not exceed 255 characters.  
 Example: `29 Arlington Avenue, Islington`

|
|customer\_birthplace  
 string

|Customer's place of birth  
 A string, must not exceed 255 characters.  
 Example: `Cambridge`

|
|customer\_city  
 string

|Customer's city of residence.  
 A string, must not exceed 255 characters.  
 Example: `London`

|
|customer\_country  
 string

|Code of the customer's country in ISO 3166-1 alpha-2 format.  
 Example: `GB`

|
|customer\_day\_of\_birth  
 string

|Customer's date of birth in `DD-MM-YYYY` format.  
 Example: `11-03-1952`

|
|customer\_email  
 string

|Customer's email address.  
 A string, must not exceed 255 characters, must contain two parts: the username and the domain name separated by the @ symbol.  
 Example: `dna@douglasadams.com`

|
|customer\_first\_name  
 string

|Customer's first name.  
 A string, must not exceed 255 characters.  
 Example: `Douglas`

|
|customer\_last\_name  
 string

|Customer's last name.  
 A string, must not exceed 255 characters.  
 Example: `Adams`

|
|customer\_middle\_name  
 string

|Customer's middle name or patronymic.  
 A string, must not exceed 255 characters.  
 Example: `Noel`

|
|customer\_phone  
 string

|Customer's full phone number, with the country code.  
 Technically, the number must include from 4 to 24 digits, and if it is allowed within the project and payment method used, punctuation marks and special symbols may be used while specifying the number \(such cases are usually mentioned separately\).  
 Examples: `443031237300`

|
|customer\_ssn  
 integer

|Last four digits of the Social Security number used for taxpayer identification, income reporting, and record-keeping purposes in the USA.  
 Example: `4942`

|
|customer\_state  
 string

|Customer's region or state.  
 A string, must not exceed 255 characters.  
 Example: `London`

|
|customer\_zip  
 string

|Customer's postal code.  
 A string, must not exceed 10 characters.  
 Example: `N17BL`

|
|billing\_address  
 string

|Street of the customer's billing address.  
 A string, must not exceed 255 characters.  
 Example: `Arlington Avenue`

|
|billing\_city  
 string

|City of the customer's billing address.  
 A string, must not exceed 255 characters.  
 Example: `London`

|
|billing\_country  
 string

|Code of the country associated with the customer's billing address in ISO 3166-1 alpha-2 format.  
 Example: `GB`

|
|billing\_postal  
 string

|Postal code of the customer's billing address.  
 A string, must not exceed 16 characters.  
 Example: `N17BL`

|
|billing\_region  
 string

|Region or state of the customer's billing address.  
 A string, must not exceed 255 characters.  
 Example: `London`

|
|billing\_region\_code  
 string

|Code of the region associated with the customer's billing address in ISO 3166-2 format.  
 Example: `LND`

|

If you need to use parameters not listed in the table above, contact the Ecommpay specialists.

**Parent topic:**[Auxiliary procedures and additional capabilities](en_PP_Additional.md)