Collecting customer data

Overview

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:

In some cases, along with data mandatory for payment processing, you may need to collect additional information from your customers in order 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).

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

To work with additional data provided by customers on the payment form, you can use payment information tabs in the Dashboard interface and final callbacks with the information about operation processing.

User scenarios

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).

A number of fields can be used to collect additional customer data on the payment form. For each field, the following display options are available:

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.
Figure 1. Additional fields display options


The field display option is determined as follows.

The field display option is determined on the basis of the two properties listed in the table and whether the field value is passed in the request.

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

Setup

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

  1. Decide which projects and 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) 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. Decide which projects and 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:
    • The field can be required or optional to fill in and/or display.
    • It is a text or dropdown input field.
    • Its name: by default standard names are provided by ecommpay; however, customisation is available.
  3. 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.
  4. 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

The following parameters can be used for collecting customer data.

Parameter Description

customer_address
string

Full customer address.
A string, must not exceed 255 characters.
Example: 29 Arlington Avenue, Islington, London

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 16 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
Parameter Description

customer_address
string

Full customer address.
Example: 29 Arlington Avenue, Islington, London

customer_birthplace
string

Customer's place of birth.
Example: Cambridge

customer_city
string

Customer's city of residence.
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.
Example: dna@douglasadams.com

customer_first_name
string

Customer's first name.
Example: Douglas

customer_last_name
string

Customer's last name.
Example: Adams

customer_middle_name
string

Customer's middle name or patronymic.
Example: Noel

customer_phone
string

Customer's phone number.
Example: 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.
Example: London

customer_zip
string

Customer's postal code.
Example: N17BL

billing_address
string

Street of the customer's billing address.
Example: Arlington Avenue

billing_city
string

City of the customer's billing address.
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.
Example: N17BL

billing_region
string

Region or state of the customer's billing address.
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.