Accept EFT Payments With PayFields - Canada
Example code and step-by-step instructions for building an EFT payment form using PayFields.
This page describes how to build an EFT payment form using PayFields:
Quickstart - Sample code and instructions for building a basic EFT payment form.
Implementation - Details about the PayFields EFT implementation.
Quickstart
Follow the steps below to create a basic EFT payment form that you can view in your web browser:
Copy the code below into a text editor.
Add your API key and merchant ID on lines 140 and 141.
Save the file with a .html extension.
Open the file in your web browser. The page will display the fields required to process an EFT transaction with PayFields.
Quickstart Code
Canada EFT Routing Number Formatting
When accepting Canadian EFT payments, the entered routing number is different from US ACH number formatting.
The routing number in Canada must appear as a 9-digit number in ACH Universal. If the Institution is only a 3-digit number, you'll add a leading zero.
Example:
If the account number listed is 01144 039
01144 being the branch number (5 digits)
039 being the institution number (3 digits)
The number MUST be entered in the following combination:
0 + (Institution number) + (Branch Number) = Payments EFT routing number entry format. See the example below.
Implementation
The sections provide details about how the EFT Quickstart page is built:
Include the JavaScript libraries - Include the PayFields and jQuery libraries in the page.
Build the PayFields script block - Authenticate your application, configure the PayFields options, create a submit button, and execute the transaction.
Add the fields to the payment page - Add
<div>elements that will contain the fields and assign the correct ID.Handle the response - Add JavaScript functions to your page that run when PayFields returns the transaction results.
Include the JavaScript libraries
PayFields requires the PayFields and the most recent jQuery JavaScript libraries. Add the following code to any page that will use the PayFields scripts:
<script src="https://code.jquery.com/jquery-3.6.0.min.js"
integrity="sha256-/xUj+3OJU5yExlq6GSYGSHk7tPXikynS7ogEvDej/m4=" crossorigin="anonymous"></script>
<script type="text/javascript" src="https:test-api.payrixcanada.com/payFieldsScript"></script>If jQuery conflicts with other global variables used in the application, you may use the noConflict feature by setting PayFields.jQuery = jQuery.noConflict(), which will ensure that jQuery will not set any global variables.
See lines 121 through 123 of the Quickstart code for context.
The Quickstart example also includes Bootstrap and popper.js to create the user interface.
Build the PayFields Script Block
The PayFields script block performs the following functions:
Authentication - Sets the
apiKeyand merchant ID values with thePayFields.config.apiKeyandPayFields.config.merchant.Configuration - Defines the type, mode, and a default amount for transactions. Identifies optional fields to ensure that PayFields works as expected.
Customization - Sets the styles that will be applied to the form elements.
Initialization - Defines the fields that will be used on the page and sets their IDs.
Execution - Creates a submit button and attaches an event listener, and runs the
PayFields.submit();function to send the payment.
The sections below define the functions of the script block in more detail.
Authentication
Use the PayFields.config functions shown below to set your API Key and Merchant ID:
// PayFields congiration goes here - API Key and Merchant ID
PayFields.config.apiKey = 'Your API Key'
PayFields.config.merchant = 'Your merchant ID'
// ==========================================================================================Configure the PayFields Options
Configure the PayFields options in your script block as shown below:
// ==========================================================================================
// Set transaction amount
PayFields.config.amount = 1000
// Tokenize bank account
PayFields.config.mode = 'txn';
// This is an echeck sale
PayFields.config.txnType = 'ecsale'
// ========================================================================================== For EFT payments, the txnType must be set to `ecsale`.
You must also set the CVV and Expiration date fields to optional, since they are required by default but are not used for EFT transactions:
// On page load, the PayFields object must know payment_cvv and expiration are optional so divs will load correctly
PayFields.customizations.optionalFields = ["#payment_cvv", "#expiration"];Customization
Set the styles that determine the appearance of the payment form:
// PayFields styling via DOM styles
// ==========================================================================================
PayFields.customizations.style = {
// Hide number div in the HTML
".number": {
display: "none"
},
".input": {
border: "1px solid #ced4da",
display: "block",
width: "12rem",
height: "34px",
padding: "0.375rem-0.75rem",
font: "12px Arial, Helvetica, sans-serif",
fontSize: ".75rem",
lineHeight: "1.5",
borderRadius: "2px",
backgroundColor: "#fff",
boxShadow: "inset 0 1px 1px rgba(0, 0, 0, .075)",
backgroundClip: "padding-box"
},
".card-icon": {
marginRight: "6rem",
marginTop: ".25rem"
}
}
// ==========================================================================================Initialization
Define the fields that will be used on the form and set their IDs. For EFT transactions, use the following fields:
number- The credit card number field. This field is required for PayFields DIVs to load, but you will not send a value for this field.name- The accountholder’s name.routing- The routing number of the accountholder’s bank.account_type- Defines whether the account is a checking or savings account.account_number- The bank account number.
The code below shows an example of the initialization:
// Initiate all fields upon page load for PayFields
// ==========================================================================================
PayFields.fields = [{
// Number must be present for PayField divs to load
type: 'number',
element: '#number'
},
{
type: 'name',
element: '#name'
},
{
type: "routing",
element: "#routing"
},
{
type: "account_type",
element: "#account_type",
},
{
type: "account_number",
element: "#account_number",
}
];
// ==========================================================================================Execution
Use the let keyword to identify the button that a customer will use to submit a payment:
// Global Variables
// ==========================================================================================
let btnEFT = document.querySelector("#btnEFT")Then add an event listener that calls the PayFields.submit() function when the button is clicked:
// Make Payment button for EFT
// ==========================================================================================
btnEFT.addEventListener('click', function () {
// Making cvv number and expiration optional for credit / debit card if EFT only
// The number element must be placed in the event listener (btnEFT)
PayFields.customizations.optionalFields = ["#number"];
// Submit payment for EFT
PayFields.submit()
})
// ==========================================================================================You must set the number field to optional in the event listener. This ensures that PayFields will not expect a card number, but that the form will be displayed as expected.
Add the fields to the payment page
Add the form fields to the <body> of your page by creating <div> elements and assigning the id values that you defined in the previous step. For example, the code below creates a <div> for the name element:
<div id="#name"></div>PayFields will display the fields on the payment page inside each <div> element and apply the appropriate styles based on the id. Be sure to also create a <button> element with the ID that you set in the configuration step.
When the customer is finished entering data and clicks the submit button, the event listener will call the PayFields.submit(); function to send the payment information to Payrix for processing.
Handle the response
Payrix returns the results of the transaction using one of the following callback function:
PayFields.onSuccess = (response) => {}- Runs when the API responds with a successful transaction or token.PayFields.onValidationFailure = () => {}- Runs when PayField validation fails before creating the API call.PayFields.onFailure = (response) => {}- Runs when the API responds with a failed transaction or token.PayFields.onFinish = (response) => {}- Runs when the API responds.PayFields.onRestore = () => {}- Runs when the restore action is run.
Fill in each function body to define the behavior of the application for each possible type of response.
PayFields Actions
The table below defines all of the actions supported by the PayFields JavaScript library:
Action | Description |
|---|---|
| Submits the PayFields data to Payrix. |
| Opens the card swipe popup. |
| Clears all the values from the fields. |
| Clears the values from the specified fields. |
| Moves the field to a new DIV. |
| Reappends the PayField with all existing values to the DIV only if the DIV has been removed. |
| Restores the values if PayFields is moved to a new DIV. |
| Displays a button in the specified element for submitting field data to Payrix . |
| Displays a button in the specified element for opening the card swipe popup. |
| Callback function that runs when the API responds with a successful transaction or token. |
| Callback function that runs when validation fails before creating the API call. |
| Callback function that runs when the API responds with a failed transaction or token. |
| Callback function that runs when the API responds. |
| Callback function that runs when the restore action is run. |
| Sets an order number for Level II/III processing. |
| Sets a tax ID number for Level II/III processing. |
| Sets a discount value for Level II/III processing. |
| Sets a shipping number for Level II/III processing. |
| Sets an duty value for Level II/III processing. |
| Adds an array of items to the order for Level II/III processing. |
| Sets known values of the cardholders billing address without displaying them on the payment page. |
| Adds additional data to the order for Level II/III processing. |
| Adds an invoice object to the order for Level II/III processing. |