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
settingskey-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.
| Name | Description |
|---|---|
accountHolderName | Prepopulates the Name field in the eCheck Information section of the iframe. User will be able to change it. |
routingNumber | Prepopulates 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.
| Name | Description |
|---|---|
cardHolderName | Prepopulates 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.
| Name | Description |
|---|---|
currency | Preselects the value in the Currency dropdown field for the currency to use for the transaction. User will be able to change it. |
description | Prepopulates the Description field in the Order Information section of the iframe. User will be able to change it. |
descriptor | Prepopulates the Descriptor field in the Order Information section of the iframe. User will be able to change it. |
customer.invoice | Prepopulates the Invoice field in the Order Information section of the iframe. User will be able to change it. |
customer.orderNumber | Prepopulates the Order Number field in the Order Information section of the iframe. User will be able to change it. |
customer.customerRef | Prepopulates the Customer Reference Number field in the Customer Information section of the iframe. User will be able to change it. |
customer.firstName | Prepopulates the First Name field in the Customer Information section of the iframe. User will be able to change it. |
customer.lastName | Prepopulates the Last Name field in the Customer Information section of the iframe. User will be able to change it. |
customer.phone | Prepopulates the Phone field in the Customer Information section of the iframe. User will be able to change it. |
customer.email | Prepopulates the Email field in the Customer Information section of the iframe. User will be able to change it. |
customer.birthDate | Prepopulates the Date of Birth field in the Customer Information section of the iframe. User will be able to change it. |
customer.nationalIdentificationNumber | Prepopulates the National Identification Number field in the Customer Information section of the iframe. User will be able to change it. |
customer.billToAddressOne | Prepopulates the Address 1 field in the Billing Information section of the iframe. User will be able to change it. |
customer.billToAddressTwo | Prepopulates the Address 2 field in the Billing Information section of the iframe. User will be able to change it. |
customer.billToCity | Prepopulates the City field in the Billing Information section of the iframe. User will be able to change it. |
customer.billToState | Prepopulates the State / Province field in the Billing Information section of the iframe. User will be able to change it. |
customer.billToPostal | Prepopulates the Postal Code field in the Billing Information section of the iframe. User will be able to change it. |
customer.billToCountry | Preselects the value in the Country dropdown field in the Billing Information section of the iframe. User will be able to change it. |
customer.billToPhone | Prepopulates the Phone field in the Billing Information section of the iframe. User will be able to change it. |
customer.shipToAddressOne | Prepopulates the Address 1 field in the Shipping Information section of the iframe. User will be able to change it. |
customer.shipToAddressTwo | Prepopulates the Address 2 field in the Shipping Information section of the iframe. User will be able to change it. |
customer.shipToCity | Prepopulates the City field in the Shipping Information section of the iframe. User will be able to change it. |
customer.shipToState | Prepopulates the State / Province field in the Shipping Information section of the iframe. User will be able to change it. |
customer.shipToPostal | Prepopulates the Postal Code field in the Shipping Information section of the iframe. User will be able to change it. |
customer.shipToCountry | Preselects the value in the Country dropdown field in the Shipping Information section of the iframe. User will be able to change it. |
customer.shipToPhone | Prepopulates the Phone field in the Shipping Information section of the iframe. User will be able to change it. |
customFields | Includes in the request any specified custom fields. This information does not display in the iframe. |
cart.items[n].item | Includes in the request the item number or code. This information does not display in the iframe. |
cart.items[n].description | Includes in the request a description of the item. This information does not display in the iframe. |
cart.items[n].quantity | Includes in the request the quantity sold. This information does not display in the iframe. |
cart.items[n].price | Includes in the request the price per item. This information does not display in the iframe. |
lodging.noShow | Includes in the request whether the customer failed to show up to their reservation (default: false). This information does not display in the iframe. |
lodging.advanceDeposit | Includes 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.checkInDate | Includes in the request the customer's check-in date. Format YYYY-MM-DD. This information does not display in the iframe. |
lodging.checkOutDate | Includes in the request the customer's check-out date. Format YYYY-MM-DD. This information does not display in the iframe. |
lodging.roomNumber | Includes in the request the customer's room number. This information does not display in the iframe. |
lodging.roomRate | Includes 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.
| Name | Description |
|---|---|
paymentType | The 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. |
saveCardToken | Enables or disables saving the card token for future use (default: true). |
paymentOptionTag | Specifies to route the transaction to a specific gateway or merchant account. |
retryOnSoftDecline | Enables or disables the transaction for decline recovery (default: false). Eligible declined transactions are automatically scheduled for retry according to the recommendation engine. |
checkFraud | Enables or disables sending a request to Kount (default: true). |
shouldUseFingerprint | Enables 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. |
verifyAvs | Enables 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. |
verifyCvc | Enables or disables whether an invalid security code prevents the card from being saved (default: false). |
verboseResponse | Specifies to include additional information in the response (default: false). |
uiOptions
The following table shows the accepted parameters for the uiOptions object.
| Name | Description |
|---|---|
css | Specifies the URL where your custom CSS file is hosted for styling the retail iframe. For example, https://tester.nexiopaysandbox.com/static/retail-example1.css |
amountSet | Prepopulates the Amount field. User will not be able to change it. |
amountDefault | Prepopulates the Amount field. User will be able to change it. |
amountMax | The maximum amount the user may enter into the Amount field. |
hideAuthOnly | Hides or displays the Auth Only checkbox (default: true). |
hideCustomerInfo | Hides 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 |
hideBilling | Hides 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 |
hideShipping | Hides 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 |
hideOrderInfo | Hides or displays the Order Information section of the iframe (default: true). This section contains the following fields: Invoice, Order Number, Description, Descriptor |
fields | 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 customer object in the data section above. |
limitCountriesTo | If 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. |
merchantIdDefault | Preselects the Processing Account dropdown field. User will be able to change it. |
merchantIdSet | Preselects 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"
}
}
Updated 6 months ago