Customizing iframe form elements

Background

Before starting this tutorial, make sure you understand the following topics from the Quick start section:

By default, each ecommerce and retail iframe displays a standard set of fields for the form.

Ecommerce iframe

For the ecommerce iframe, you can show or hide all these elements:

Element

Parameters for

uiOptions

Default value

Description

Submit button

displaySubmitButton

false

Set to true to display a submit button within the iframe. If you leave it as false, you must provide a submission button elsewhere on the web page.

Billing fields

hideBilling.hideAddressOne
hideBilling.hideAddressTwo
hideBilling.hideCity
hideBilling.hideState
hideBilling.hidePostal
hideBilling.hideCountry
hideBilling.hidePhone

false (for all)

Set to true for one or more of these parameters to hide the indicated field from the form.

Optionally, set hideBilling to true to hide all the billing fields.

Security code field

hideCvc

false

Set to true to hide the security code field.

Country selection menu

limitCountriesTo

All

Leave this parameter out of the request in order to show all available countries, based on the merchant ID (MID).

If you add this parameter and provide an array of country codes, only the specified countries display in the selection list. For example, specify ["CN","DE","NL","ES","US"] to display "China", "Germany", "Netherlands", Spain", and "United States" in the list.

Form validation for security code

uiOptions.requireCvc

true

Set to false to allow form submission without requiring a security code.

You can customize the elements that display by following these steps:

  1. Send a POST request to the Create one-time-use token endpoint.

    • Include the uiOptions object and one or more of the parameters from the table above in the body of the request.

      For example, to display a submit button, limit the countries to the United States and Canada, and to hide the phone and second address line fields, the request looks similar to the following:

      curl -X POST https://api.nexiopaysandbox.com/pay/v3/token \
        -H 'Content-Type: application/json' \
        -H 'Accept: application/json' \
        -H 'Authorization: Basic [Base64_encoded_login]' \
        -d '{
        "uiOptions": {
          "displaySubmitButton": true,
          "limitCountriesTo": ["CA","US"],
          "hideBilling": {
            "hideAddressTwo": true,
            "hidePhone": true
          }
        }
      }'

      The response includes a token parameter. Encoded within this value is the settings for the form. Save this token for use in the next step.

      {
        "expiration": "2022-09-18T15:43:05.664Z",
        "fraudUrl": "https://api.nexiopaysandbox.com/pay/v3/fingerprint?token=830d36f6-a5e3-4455-9600-3a55b63e2fc2",
        "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2"
      }

  2. Request the iframe to display on the page using the token from the response in step 1.

    You may display a customized form for the iframe for any of the following types of pages:

    For example, the following request uses the token to return the HTML for an iframe for a checkout page for a card, with the settings as specified in step 1.

    curl -X GET https://api.nexiopaysandbox.com/pay/v3?token=830d36f6-a5e3-4455-9600-3a55b63e2fc2' 

Retail iframe

For the retail iframe, you can show or hide all these elements:

Element

Parameters for

uiOptions

Default value

Description

Processing Account

merchantIdSet

None

Preselects the Processing Account dropdown field to the specified merchant ID (MID) and hides the field from the user.

Auth Only

hideAuthOnly

true

Hides or displays the Auth Only checkbox.

Customer Info section

hideCustomerInfo

true

Hides or displays the Customer Information section of the iframe. This section contains the following fields: First Name, Last Name, Phone, Email, Customer Reference Number, Date of Birth, National Identification Number

Billing Info section

hideBilling

false

Hides or displays all billing fields in the Billing Information section. This section contains the following fields: Country, Address 1, Address 2, City, State / Province, Postal Code, Phone

Shipping Info section

hideShipping

true

Hides or displays all shipping fields in the Shipping Information section. This section contains the following fields: Same as billing information from the [, Country, Address 1, Address 2, City, State / Province, Postal Code, Phone

Order Info section

hideOrderInfo

true

Hides or displays the Order Information section of the iframe. This section contains the following fields: Invoice, Order Number, Description, Descriptor

Country selection menu

limitCountriesTo

All

Leave this parameter out of the request in order to show all available countries, based on the merchant ID (MID).

If you add this parameter and provide an array of two-character (Alpha-2) ISO country codes, only the specified countries display in the selection list. For example, specify ["CN","DE","NL","ES","US"] to display "China", "Germany", "Netherlands", Spain", and "United States" in the list.

Customer, Billing, and Shipping fields

fields

Varies

Specifies which fields to display in the retail iframe's form, and whether they are required or optional for the end user filling out the form. If you include this fields object, any of the possible fields that are not specifically defined are excluded from the form.

For each field included, you configure the value as one of the following:
- "required" - The field displays and the user must enter a value to submit the form successfully.
- "optional" - The field displays and the user can submit the form with or without providing a value.

For example, the following displays a form with only a required firstName field and an optional lastName field:\

"fields": {  
  "firstName": "required",  
  "lastName": "optional"  
}

This object can have one or more of the following fields specified: billToCountry, billToAddressOne, billToAddressTwo, billToCity, billToState, billToPostal, billToPhone, shipToCountry, shipToAddressOne, shipToAddressTwo, shipToCity, shipToState, shipToPostal, shipToPhone, invoice, orderNumber, description, descriptor, firstName, lastName, phone, email, customerRef, birthDate, nationalIdentificationNumber.

For additional information about a field, see the Customizing the retail iframe topic.

In order to customize the retail iframe, follow the steps in Customizing the retail iframe.