ProductsEPX Hosted Checkout Integration Guide
- Sign up for a free North Developer account.
- Review the guide below, then demo this product by making a test payment in our Sandbox environment using the sample credit card data provided.
- Apply for a Merchant Processing Account. Once approved, a Merchant ID (MID) will be provided to you.
- After you receive a MID, you or an authorized contact will need to email the Equipment Solutions team at equipmentsolutions@paymentshub.com for Production credentials. Please include your MID in the subject line of the email. For example: “MID 1234567 Requesting Production Credentials for EPX Hosted Checkout".
- After you receive an email with production credentials (4-Part Key), navigate to the EPX Hosted Checkout configuration module. Fill out the form with the following information:
- Merchant Name: DBA name
- Receipt Email: Business email address where copies of receipts will be sent
- 4-Part Key: Provided by the Equipment Solutions team
- Click “Submit” and the configuration module will load. The configuration module provides three options for integrating EPX Hosted Checkout in your environment: a payment button that can be added to your website, a link that can be sent to customers, or a POST API request.
- Build your payment form within the module. EPX Hosted Checkout is available in the production environment only, so a live preview pane is provided to view your form while you build it. To create multiple payment forms, click the Checkout Id drop-down menu, then click the plus sign (+). Edit the settings as follows:
- Link Type:
- Button: No-code payment button that can be added to your site. The button opens the payment form in a pop-up box.
- Link: No-code link that can be sent to customers. The link opens the payment form in a new browser tab.
- POST: Low-code POST API request that offers the most control and customization of your payment solution. This option integrates the payment form into your site's current page.
- Label: Enter your DBA name (this is the name displayed in the Checkout Id field).
- Color Scheme: Edit the color to match your website.
- Sections: Add a section to the form using the plus sign (+) at the bottom of the Sections list. Delete a section by selecting it to expand its settings and clicking the “Delete” button. Click on a section to adjust its settings:
- Page: Create multiple pages to separate the sections of your payment form. A “Next” button will appear in the bottom right corner of the form to prompt customers to continue to the next section.
- Hide Header: Show or hide the form section heading.
- Inputs: Edit the attributes for the input fields (field size, required field, show/hide field label). Create new input fields using the plus sign (+) at the bottom of the Inputs list.
- Click the “Save Changes” button. To make edits, just navigate back to the EPX Hosted Checkout Configuration Module while signed in to your North Developer account.
- Follow the integration instructions below based on the type selected: Button, Link, or POST.
Payment Button
Adding the EPX Hosted Checkout Button to your website consists of three steps:
- Add the JavaScript link. Copy the HTML code below and paste it in the header or body of your HTML page.
HTML
- Add the HTML button. After you build your form in the configuration module, copy the HTML code provided in the module and paste it in the body of your HTML page. The HTML button supports a number of attributes, but only data-terminal-profile-id and class="EPX-button" are required. See the Attribute Table below for a complete list of button attributes and accepted values. Internal and external CSS can be applied to the button element, although inline CSS is not recommended.
Sample HTML button with minimum required attributes:
HTML
- Optionally, add a callback function. The callback function can be used to retrieve transaction response data and execute custom actions if the transaction is successful. If you wish to use a callback function, please contact us for integration support.
By default, after a successful transaction, a modal displays the approval information which has a "Close" button to exit out of the modal. If the callback function is configured, it will trigger once the user clicks "Close." The callback-before-close flag allows the function to be triggered immediately after a successful transaction.
If desired, EPX's success message can be skipped entirely and the customer can be directed to the merchant's custom success page. The callback function can be triggered when the user clicks close while in the payment form, and we will return a response.
The attribute data-callback-function is required to be present in the button element to use a callback function. The dynamic fields in the response are the result of creating extra fields in the configuration module.
Button Attribute
HTML
Callback Function
HTML
Response Example
Payment Link
To add the Hosted Checkout Link to your website, copy the link provided in the configuration module. The only required parameter is terminal_profile_id=XXXX, which is used to link the form to your MID, display your color and field configurations, and ensure that the transaction will be processed under the correct account.
To add more query parameters to your link, refer to the Attribute Table below for a complete list of attributes and accepted values. The parameters and values must be placed at the end of the link following this format: parameter=value. Multiple parameter/value pairs must be separated by an ampersand: parameterOne=value¶meterTwo=value. Parameters can be placed in any order.
Example link that prepopulates Amount and Billing Name into the form:
Payment POST
Please contact us to begin a Hosted Checkout POST integration. Adding the POST API call to your website involves four main steps:
- Copy the code provided in the configuration module and paste it into your HTML file.
- Customize your CSS and callback functions. Resources to assist with development, including test data, are provided here.
- Contact us to request that your domain(s) be added to our Google reCaptcha account.
- Provide raw request and response data to us for every transaction type that will be used in production to obtain our processor certification.
When logged in, you can use the Integration Tracker to view the status of your integration, notes from meetings with Integration Engineers, resources related to your solution, and more by clicking the User profile icon in the top right corner of the screen and selecting Integrations.
The code that you'll add to your HTML file in step 1 will include the following:
Link to post.js
Link to Google reCaptcha
Function to handle the response. The response is returned as a JSON string, not a JSON object. Use JSON.parse(msg) or some other method if the object is needed.
HTML form, including at minimum the following:
- Card number field
- Expiration date field
- Amount field
- Description field (this can be used as custom field based on the business’s needs)
- Hidden fields:
- reCaptcha. If you wish to implement Google reCaptcha in a different way, please make sure that you are using our sitekey:
6LcCXwwUAAAAAO8617hw-277eL5cMAJ5SBsebhWk
And please make sure that the value of the reCaptcha field is being populated with reCaptcha response:
- publicKey (this value is the base64 encoded piece of JSON: { "terminalProfileId": 12345 } )
- successCallback
- failureCallback
- Submit button
Refer to the Attribute Table below for a complete list of attributes and accepted values.
Callback Function
An optional callback function can be used to retrieve the response of a successfully processed transaction. By default, after a successful transaction, a modal displays the approval information which has a "Close" button to exit out of the modal. If the callback function is configured, it will trigger once the user clicks "Close." The callback-before-close flag allows the function to be triggered immediately after a successful transaction.
If desired, EPX's success message can be skipped entirely and the customer can be directed to the merchant's custom success page. The callback function can be triggered when the user clicks close while in the payment form, and we will return a response.
The attribute data-callback is required to use a callback function. The dynamic fields in the response are the result of creating extra fields in the configuration module.
Example HTML
HTML
JSON Response Example
Attribute Table
| Button Attribute | Link Attribute | POST Attribute | Description | Accepted Values |
|---|---|---|---|---|
data-amount= | &amount= | Amount | Prepopulates a value into the amount field and disables editing. | 0.01 - 999999.99 |
data-checkout-id= | &checkout_id= | [Field not available for Hosted Checkout POST] | Corresponds to the Label to differentiate between multiple form configurations. | Integer |
data-callback-function= | [Field not available for Hosted Checkout Link] | data-callback | Specifies a JavaScript function name that will execute on payment success. | JavaScript function name |
data-invoice-num= | &invoice_no= | Invoice Number | Prepopulates a value into the invoice field and disables editing. | Alphanumeric (25 characters) |
data-description= | &description= | Description | Prepopulates a value into the description field and disables editing. | Alphanumeric (25 characters) |
data-billing-address= | &billing_address= | Billing Street Address | Prepopulates a value into the billing address field and disables editing. | Alphanumeric |
data-billing-name= | &billing_name= | Billing Name | Prepopulates a value into the billing name field and disables editing. | Space-separated alphanumeric |
data-billing-city= | &billing_city= | Billing City | Prepopulates a value into the billing city field and disables editing. | Alphanumeric (25 characters) |
data-billing-state= | &billing_state= | Billing State | Prepopulates a value into the billing state field and disables editing. | U.S. state abbreviations |
data-billing-postal-code= | &billing_postal_code= | Billing Postal Code | Prepopulates a value into the billing zip field and disables editing. | 5-digit U.S. postal code |
data-billing-country= | &billing_country= | Billing Country | Prepopulates a value into the billing country field and disables editing. | Full country name |
data-shipping-address= | &shipping_address= | Shipping Street Address | Prepopulates a value into the shipping address field and disables editing. | Alphanumeric (25 characters) |
data-shipping-name= | &shipping_name= | Shipping Name | Prepopulates a value into the shipping name field and disables editing. | Space-separated alphanumeric |
data-shipping-city= | &shipping_city= | Shipping City | Prepopulates a value into the shipping city field and disables editing. | Alphanumeric (25 characters) |
data-shipping-state= | &shipping_state= | Shipping State | Prepopulates a value into the shipping state field and disables editing. | U.S. state abbreviations |
data-shipping-postal-code= | &shipping_postal_code= | Shipping Postal Code | Prepopulates a value into the shipping zip field and disables editing. | 5-digit U.S. postal code |
data-shipping-country= | &shipping_country= | Shipping Country | Prepopulates a value into the shipping country field and disables editing. | Full country name |
data-email= | &email= | Prepopulates a value into the email field and disables editing. | local-part@domain | |
data-company= | [Field not available for Hosted Checkout Link] | [Field not available for Hosted Checkout POST] | Prepopulates a value into the company name field and disables editing. | Alphanumeric (25 characters) |
data-use-test-values= | &use_test_values= | [Field not available for Hosted Checkout POST] | Prepopulates test data into all fields to assist with the testing process. | true or false |
[Field not available for Hosted Checkout Button] | [Field not available for Hosted Checkout Link] | Captcha | Link to Google reCaptcha. | reCaptcha response |
[Field not available for Hosted Checkout Button] | [Field not available for Hosted Checkout Link] | publicKey | The base64 encoded piece of JSON: { 'terminalProfileId': 12345 }. | Integer |