Customizing the retail iframe

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

You can customize the retail/MOTO iframe in the call to load it (either directly via the URL or loading an iframe on your own webpage) at https://retail.nexiopaysandbox.com.

To make this customization, include the settings key and a value that is an object of parameters.

📘

Note

The content in the settings key-value pair should be escaped or URL encoded so that the URL is safe to send over the internet. For additional information about what URL encoding is and how to do it, see the HTML URL Encoding Reference at W3Schools.

You can include the settings key-value pair with or without the simple login for authentication. For example:

https://retail.nexiopaysandbox.com/?settings=%7B%22uiOptions%22%3A%7B%22saveCard%22%3Atrue%7D%7D
https://retail.nexiopaysandbox.com/?simpleLogin={key}&settings=%7B%22processingOptions%22%3A%7B%22amountDefault%22%3A%2220%22%7D%7D

Customization options

You can include several different parameters for settings.

The following sections and tables provide information about each main object and parameter.

bank

The following table shows the available parameter for the bank object, for running an echeck transaction.

NameDescription
accountHolderNamePrepopulates the Name field in the eCheck Information section of the iframe. User will be able to change it.
routingNumberPrepopulates the Routing Number field in the eCheck Information section of the iframe. User will be able to change it.

card

The following table shows the available parameter for the card object.

NameDescription
cardHolderNamePrepopulates the Name field in the Card Information section of the iframe. User will be able to change it.

data

The following table shows the available parameters for the data object.

NameDescription
currencyPreselects the value in the Currency dropdown field for the currency to use for the transaction. User will be able to change it.
descriptionPrepopulates the Description field in the Order Information section of the iframe. User will be able to change it.
descriptorPrepopulates the Descriptor field in the Order Information section of the iframe. User will be able to change it.
customer.invoicePrepopulates the Invoice field in the Order Information section of the iframe. User will be able to change it.
customer.orderNumberPrepopulates the Order Number field in the Order Information section of the iframe. User will be able to change it.
customer.customerRefPrepopulates the Customer Reference Number field in the Customer Information section of the iframe. User will be able to change it.
customer.firstNamePrepopulates the First Name field in the Customer Information section of the iframe. User will be able to change it.
customer.lastNamePrepopulates the Last Name field in the Customer Information section of the iframe. User will be able to change it.
customer.phonePrepopulates the Phone field in the Customer Information section of the iframe. User will be able to change it.
customer.emailPrepopulates the Email field in the Customer Information section of the iframe. User will be able to change it.
customer.birthDatePrepopulates the Date of Birth field in the Customer Information section of the iframe. User will be able to change it.
customer.nationalIdentificationNumberPrepopulates the National Identification Number field in the Customer Information section of the iframe. User will be able to change it.
customer.billToAddressOnePrepopulates the Address 1 field in the Billing Information section of the iframe. User will be able to change it.
customer.billToAddressTwoPrepopulates the Address 2 field in the Billing Information section of the iframe. User will be able to change it.
customer.billToCityPrepopulates the City field in the Billing Information section of the iframe. User will be able to change it.
customer.billToStatePrepopulates the State / Province field in the Billing Information section of the iframe. User will be able to change it.
customer.billToPostalPrepopulates the Postal Code field in the Billing Information section of the iframe. User will be able to change it.
customer.billToCountryPreselects the value in the Country dropdown field in the Billing Information section of the iframe. User will be able to change it.
customer.billToPhonePrepopulates the Phone field in the Billing Information section of the iframe. User will be able to change it.
customer.shipToAddressOnePrepopulates the Address 1 field in the Shipping Information section of the iframe. User will be able to change it.
customer.shipToAddressTwoPrepopulates the Address 2 field in the Shipping Information section of the iframe. User will be able to change it.
customer.shipToCityPrepopulates the City field in the Shipping Information section of the iframe. User will be able to change it.
customer.shipToStatePrepopulates the State / Province field in the Shipping Information section of the iframe. User will be able to change it.
customer.shipToPostalPrepopulates the Postal Code field in the Shipping Information section of the iframe. User will be able to change it.
customer.shipToCountryPreselects the value in the Country dropdown field in the Shipping Information section of the iframe. User will be able to change it.
customer.shipToPhonePrepopulates the Phone field in the Shipping Information section of the iframe. User will be able to change it.
customFieldsIncludes in the request any specified custom fields. This information does not display in the iframe.
cart.items[n].itemIncludes in the request the item number or code. This information does not display in the iframe.
cart.items[n].descriptionIncludes in the request a description of the item. This information does not display in the iframe.
cart.items[n].quantityIncludes in the request the quantity sold. This information does not display in the iframe.
cart.items[n].priceIncludes in the request the price per item. This information does not display in the iframe.
lodging.noShowIncludes in the request whether the customer failed to show up to their reservation (default: false). This information does not display in the iframe.
lodging.advanceDepositIncludes in the the request whether the customer paid a deposit in advance of their reservation (default: false). This information does not display in the iframe.
lodging.checkInDateIncludes in the request the customer's check-in date. Format YYYY-MM-DD. This information does not display in the iframe.
lodging.checkOutDateIncludes in the request the customer's check-out date. Format YYYY-MM-DD. This information does not display in the iframe.
lodging.roomNumberIncludes in the request the customer's room number. This information does not display in the iframe.
lodging.roomRateIncludes in the request the room's rate, per day. This information does not display in the iframe.

isAuthOnly

You can include the isAuthOnly parameter to toggle whether the transaction is auth only. The default setting is false.

📘

Note

Although you can set this parameter to true, if the Auth Only checkbox is set to also display, the system does not automatically select the checkbox.

shouldUpdateCard

You can include the shouldUpdateCard parameter to toggle whether to enable the card's account updater enrollment tag. When true, the card token is tagged for being sent to the account updater provider. The default setting is true.

📘

Note

The card will not be registered until the merchant account is enrolled. See the Enrollment tag table for more information.

processingOptions

The following table shows the accepted parameters for the processingOptions object.

NameDescription
paymentTypeThe type of transaction being processed using stored payment credentials. Use this parameter to properly flag initial and subsequent transactions. For more information about this parameter and when to use each option, see the paymentType documentation and reference table.
saveCardTokenEnables or disables saving the card token for future use (default: true).
paymentOptionTagSpecifies to route the transaction to a specific gateway or merchant account.
retryOnSoftDeclineEnables or disables the transaction for decline recovery (default: false). Eligible declined transactions are automatically scheduled for retry according to the recommendation engine.
checkFraudEnables or disables sending a request to Kount (default: true).
shouldUseFingerprintEnables or disables when a device fingerprint was created while saving a card token (default: true). The card's stored fingerprint will be used by default, but you may choose not to use it by setting this parameter to false.
verifyAvsEnables or disables the Address Verification Service (AVS) when saving a card token for US-based addresses (default: 0). See the Settings for AVS table for a complete list of options.
verifyCvcEnables or disables whether an invalid security code prevents the card from being saved (default: false).
verboseResponseSpecifies to include additional information in the response (default: false).

uiOptions

The following table shows the accepted parameters for the uiOptions object.

NameDescription
cssSpecifies the URL where your custom CSS file is hosted for styling the retail iframe. For example, https://tester.nexiopaysandbox.com/static/retail-example1.css
amountSetPrepopulates the Amount field. User will not be able to change it.
amountDefaultPrepopulates the Amount field. User will be able to change it.
amountMaxThe maximum amount the user may enter into the Amount field.
hideAuthOnlyHides or displays the Auth Only checkbox (default: true).
hideCustomerInfoHides or displays the Customer Information section of the iframe (default: true). This section contains the following fields: First Name, Last Name, Phone, Email, Customer Reference Number, Date of Birth, National Identification Number
hideBillingHides or displays all billing fields in the Billing Information section (default: false). This section contains the following fields: Country, Address 1, Address 2, City, State / Province, Postal Code, Phone
hideShippingHides or displays all shipping fields in the Shipping Information section (default: true). This section contains the following fields: Same as billing information (checkbox), Country, Address 1, Address 2, City, State / Province, Postal Code, Phone
hideOrderInfoHides or displays the Order Information section of the iframe (default: true). This section contains the following fields: Invoice, Order Number, Description, Descriptor
fieldsSpecifies 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 customer object in the data section above.
limitCountriesToIf this array is nonempty, the Country Dropdown field will be limited to the countries on the list.
Note: These must be the two-character (Alpha-2) ISO country codes.
merchantIdDefaultPreselects the Processing Account dropdown field. User will be able to change it.
merchantIdSetPreselects the Processing Account dropdown field and hides it. User will not be able to change it.

Example with all options

The following example shows the URL encoded string of all the possible options as well as the JSON view of them.

🚧

Important

These examples are for demonstration purposes only because some of the options contradict each other.

%7B%22isAuthOnly%22%3Afalse%2C%22bank%22%3A%7B%22accountHolderName%22%3A%22John%20Doe%22%2C%22routingNumber%22%3A%22231375151%22%7D%2C%22card%22%3A%7B%22cardHolderName%22%3A%22John%20H%20Doe%22%7D%2C%22data%22%3A%7B%22currency%22%3A%22USD%22%2C%22description%22%3A%22This%20is%20a%20test%20purchase%22%2C%22descriptor%22%3A%22This%20is%20a%20descriptor%22%2C%22customer%22%3A%7B%22invoice%22%3A%22IN0001%22%2C%22orderNumber%22%3A%22210058A%22%2C%22customerRef%22%3A%22RP006%22%2C%22firstName%22%3A%22John%22%2C%22lastName%22%3A%22Doe%22%2C%22phone%22%3A%221555555555%22%2C%22email%22%3A%22jdoe%40example%2Ecom%22%2C%22birthDate%22%3A%221990%2D12%2D05%22%2C%22nationalIdentificationNumber%22%3A%225471300000000003%22%2C%22billToAddressOne%22%3A%222147%20West%20Silverlake%20Drive%22%2C%22billToAddressTwo%22%3A%22Apt%2042%22%2C%22billToCity%22%3A%22Scranton%22%2C%22billToState%22%3A%22PA%22%2C%22billToPostal%22%3A%2218503%22%2C%22billToCountry%22%3A%22US%22%2C%22billToPhone%22%3A%221555555555%22%2C%22shipToAddressOne%22%3A%221725%20Slough%20Avenue%22%2C%22shipToAddressTwo%22%3A%22Suite%20200%22%2C%22shipToCity%22%3A%22Scranton%22%2C%22shipToState%22%3A%22PA%22%2C%22shipToPostal%22%3A%2218505%22%2C%22shipToCountry%22%3A%22US%22%2C%22shipToPhone%22%3A%221555555555%22%7D%2C%22customFields%22%3A%7B%22exampleKey%22%3A%22Example%20string%22%7D%2C%22cart%22%3A%7B%22items%22%3A%5B%7B%22item%22%3A%22913261%22%2C%22description%22%3A%22Hammermill%20Premium%208%2E5%20x%2011%20Color%20Copy%20Paper%2C%2028%20lbs%2E%20500%2FReam%22%2C%22quantity%22%3A8%2C%22price%22%3A16%2E49%2C%22type%22%3A%22sale%22%7D%5D%7D%2C%22lodging%22%3A%7B%22advanceDeposit%22%3Atrue%2C%22checkInDate%22%3A%222018%2D12%2D31%22%2C%22checkOutDate%22%3A%222019%2D01%2D05%22%2C%22noShow%22%3Afalse%2C%22roomNumber%22%3A14%2C%22roomRate%22%3A143%2E99%7D%7D%2C%22shouldUpdateCard%22%3Atrue%2C%22processingOptions%22%3A%7B%22saveCardToken%22%3Atrue%2C%22paymentOptionTag%22%3A%22usaepay%22%2C%22checkFraud%22%3Atrue%2C%22shouldUseFingerprint%22%3Atrue%2C%22verifyAvs%22%3A0%2C%22verifyCvc%22%3Afalse%2C%22verboseResponse%22%3Atrue%7D%2C%22uiOptions%22%3A%7B%22css%22%3A%22https%3A%2F%2Ftester%2Enexiopaysandbox%2Ecom%2Fstatic%2Fretail%2Dexample1%2Ecss%22%2C%22amountSet%22%3A%2210%2E99%22%2C%22amountDefault%22%3A%229%2E99%22%2C%22amountMax%22%3A%2220%2E00%22%2C%22hideAuthOnly%22%3Atrue%2C%22hideCustomerInfo%22%3Afalse%2C%22hideBilling%22%3Afalse%2C%22hideShipping%22%3Afalse%2C%22hideOrderInfo%22%3Afalse%2C%22fields%22%3A%7B%22description%22%3A%22optional%22%2C%22descriptor%22%3A%22optional%22%2C%22invoice%22%3A%22required%22%2C%22orderNumber%22%3A%22required%22%2C%22customerRef%22%3A%22optional%22%2C%22firstName%22%3A%22required%22%2C%22lastName%22%3A%22optional%22%2C%22phone%22%3A%22optional%22%2C%22email%22%3A%22optional%22%2C%22birthDate%22%3A%22optional%22%2C%22nationalIdentificationNumber%22%3A%22optional%22%2C%22billToAddressOne%22%3A%22required%22%2C%22billToAddressTwo%22%3A%22optional%22%2C%22billToCity%22%3A%22required%22%2C%22billToState%22%3A%22required%22%2C%22billToPostal%22%3A%22required%22%2C%22billToCountry%22%3A%22required%22%2C%22billToPhone%22%3A%22optional%22%2C%22shipToAddressOne%22%3A%22required%22%2C%22shipToAddressTwo%22%3A%22optional%22%2C%22shipToCity%22%3A%22required%22%2C%22shipToState%22%3A%22required%22%2C%22shipToPostal%22%3A%22required%22%2C%22shipToCountry%22%3A%22required%22%2C%22shipToPhone%22%3A%22optional%22%7D%22limitCountriesTo%22%3A%5B%22US%22%2C%22CA%22%2C%22MX%22%2C%22GB%22%5D%2C%22merchantIdDefault%22%3A%22000999%22%2C%22merchantIdSet%22%3A%22000999%22%7D%7D
{
  "isAuthOnly": false,
  "bank": {
    "accountHolderName": "John Doe",
    "routingNumber": "231375151"
  },
  "card": {
    "cardHolderName": "John H Doe"
  },
  "data": {
    "currency": "USD",
    "description": "This is a test purchase",
    "descriptor": "This is a descriptor",
    "customer": {
      "invoice": "IN0001",
      "orderNumber": "210058A",
      "customerRef": "RP006",
      "firstName": "John",
      "lastName": "Doe",
      "phone": "1555555555",
      "email": "[email protected]",
      "birthDate": "1990-12-05",
	  "nationalIdentificationNumber": "5471300000000003",
      "billToAddressOne": "2147 West Silverlake Drive",
      "billToAddressTwo": "Apt 42",
      "billToCity": "Scranton",
      "billToState": "PA",
      "billToPostal": "18503",
      "billToCountry": "US",
      "billToPhone": "1555555555",
      "shipToAddressOne": "1725 Slough Avenue",
      "shipToAddressTwo": "Suite 200",
      "shipToCity": "Scranton",
      "shipToState": "PA",
      "shipToPostal": "18505",
      "shipToCountry": "US",
      "shipToPhone": "1555555555"
    },
    "customFields": {
      "exampleKey": "Example string"
    },
    "cart": {
      "items": [
        {
          "item": "913261",
          "description": "Hammermill Premium 8.5 x 11 Color Copy Paper, 28 lbs. 500/Ream",
          "quantity": 8,
          "price": 16.49,
          "type": "sale"
        }
      ]
    },
    "lodging": {
      "advanceDeposit": true,
      "checkInDate": "2018-12-31",
      "checkOutDate": "2019-01-05",
      "noShow": false,
      "roomNumber": 14,
      "roomRate": 143.99
    }
  },
  "shouldUpdateCard": true,
  "processingOptions": {
    "saveCardToken": true,
	"paymentOptionTag": "usaepay",
	"checkFraud": true,
	"shouldUseFingerprint": true,
    "verifyAvs": 0,
    "verifyCvc": false,
	"verboseResponse": true
  },
  "uiOptions": {
    "css": "https://tester.nexiopaysandbox.com/static/retail-example1.css",
    "amountSet": "10.99",
	"amountDefault": "9.99",
	"amountMax": "20.00",
	"hideAuthOnly": true,
	"hideCustomerInfo": false,
	"hideBilling": false,
	"hideShipping": false,
	"hideOrderInfo": false,
	"fields": {
	  "description": "optional",
	  "descriptor": "optional",
	  "invoice": "required",
	  "orderNumber": "required",
	  "customerRef": "optional",
	  "firstName": "required",
	  "lastName": "optional",
	  "phone": "optional",
	  "email": "optional",
	  "birthDate": "optional",
	  "nationalIdentificationNumber": "optional",
	  "billToAddressOne": "required",
	  "billToAddressTwo": "optional",
	  "billToCity": "required",
	  "billToState": "required",
	  "billToPostal": "required",
	  "billToCountry": "required",
	  "billToPhone": "optional",
	  "shipToAddressOne": "required",
	  "shipToAddressTwo": "optional",
	  "shipToCity": "required",
	  "shipToState": "required",
	  "shipToPostal": "required",
	  "shipToCountry": "required",
	  "shipToPhone": "optional"
	}
	"limitCountriesTo": [
      "US",
      "CA",
      "MX",
      "GB"
    ],
	"merchantIdDefault": "000999",
	"merchantIdSet": "000999"
  }
}