Example code and detailed, step-by-step instructions for building a payment page using PayFields.
This page includes a Quickstart section, which provides sample code for a basic payment page using all of the available fields provided by PayFields, an Implementation section, which provides details about how to incorporate PayFields into a custom payment page, and definitions of all of the actions supported by PayFields.
Quickstart
Follow the steps below to open a basic checkout page with PayFields already integrated:
Copy the code below into a text editor.
Add your API key and merchant ID on lines 97 and 99.
Save the file with a .html extension.
Open the file in your web browser. The page will display all of the fields available for use on your custom payment page: card number, expiration date, CVV, and billing address.
Quickstart Code
Click to expand the PayFields Quickstart code.
HTML
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<script type="text/javascript" src="https://code.jquery.com/jquery-2.2.4.min.js"></script>
<!-- Be sure to set the proper url-->
<!-- Sandbox URL -->
<script type="text/javascript" src="https://test-api.payrixcanada.com/payFieldsScript"></script>
<!-- Production URL -->
<!-- <script type="text/javascript" src="https://api.payrixcanada.com/payFieldsScript"></script> -->
<title>Payfields Testing</title>
<style media="screen">
#button {
text-transform: uppercase;
cursor: pointer;
border: none;
width: 150px;
outline: none;
height: 30px;
background-color: rgb(69,67,67);
color: white;
}
#swipe {
text-transform: uppercase;
cursor: pointer;
border: none;
width: 150px;
outline: none;
height: 30px;
background-color: rgb(0,0,0);
color: white;
}
/*
Recommended minimum div sizes to properly display iframes. We need to
set div height and width when passing custom styles. When no custom
styles are passed then it is automatically set to optimal height and
width
*/
.form-row {
height: 73px;
width: 300px;
}
.address-row {
height: 438px;
width: 300px;
}
</style>
</head>
<body>
<div>
<label for="number">
Number:
</label>
<!-- Div for number field iframe -->
<div id="number" class="form-row">
</div>
</div>
<div >
<label for="expiration">
Expiration:
</label>
<!-- Div for expiration field iframe -->
<div id="expiration" class="form-row">
</div>
</div>
<div>
<label for="cvv">
CVV:
</label>
<!-- Div for cvv field iframe -->
<div id="cvv" class="form-row">
</div>
</div>
<div>
<label for="name">
Name:
</label>
<!-- Div for name field iframe -->
<div id="name" class="form-row">
</div>
</div>
<div>
<label for="address">
<!-- Address: -->
</label>
<!-- Div for address field iframe -->
<div id="address" class="address-row">
</div>
</div>
<div class="button-container">
<button type="button" id="button" name="Submit">Submit</button>
<button id="swipe" type="button" name="button">Swipe</button>
</div>
<script>
// Api key
PayFields.config.apiKey = "APIKEY";
// Merchant id
PayFields.config.merchant = "t1_mer_merchant_id";
// Option to Enable swipe
//PayFields.config.swipe = true;
// Set the amount in cents on load. This can be set to null and modified
// onClick or onEdit
PayFields.config.amount = '0';
// Option to create token while also a transaction. Remove this line to run a sale
PayFields.config.mode = 'txnToken';
// Setting Transaction type to auth. Remove this line to run a full sale
//PayFields.config.txnType = 'auth';
// Set this to use Payfields to ONLY generate a token.
//PayFields.config.txnType = 'token';
// To pass in an address for a transaction, use the below.
// Fields address, city, province, postalCode, email, and phone will only be set
// if there are no address fields setup
// Fields address2, country, and company will always be set regardless
// if address fields are setup since they are considered extra billing
// address fields.
PayFields.config.billingAddress = {
address: '123 Sussex Drive',
city: 'Ottawa',
province: 'ON',
postalCode: 'K1A 0A1',
email: 'test@test.com',
phone: '2223456789',
address2: 'suite 555',
company: 'Essential Co',
country: 'CAN'
};
// Fields that will be used, each field will be passed as an object
// the type of field and element needs to be passed. Values are optional
// and those inputs will be filled with the values, they will be
// disabled
PayFields.fields = [
{
type: "number",
element: "#number",
values: {number: "4242424242424242"}
},
{
type: "cvv",
element: "#cvv",
},
{
type: "name",
element: "#name",
},
//{
// type: "address",
// element: "#address",
//},
{
type: "expiration",
element: "#expiration",
}
];
// Passing Custom Styles. We pass a style object with the class(es) to be
// styled. Specific classes such as .number have priority over more generic
// classes such as .input . In other words classes will stack on each other
// however in case of same property on both classes are to be styled then
// class with highest priority will overwrite the other. All classes will be
// described further below
PayFields.customizations = {
style: {
// All address fields class.
".address-input": {
borderColor: "rgb(119,136,153)",
borderStyle: "solid",
borderBottomWidth: "1px"
},
// All fields
".input": {
borderColor: "rgb(69,67,67)",
borderStyle: "solid",
borderBottomWidth: "1px"
},
// All error spans
".form-error": {
color: "rgb(255, 0, 128)"
},
// Address error spans
".address-form-error": {
color: "rgb(0,139,139)"
}
}
};
// This would be handled automatically if a button element is passed to
// Payfields.button
$("#button").on("click", function(){
// Disable the button to avoid multiple calls
$(this).prop("disabled", true);
// Submit
PayFields.submit();
});
// This would be handled automatically if a button element is passed to
// Payfields.swipeButton
$("#swipe").on("click", function(){
// Swipe
PayFields.swipePopup();
});
// On validation error(s), this would handled automatically if an button
// element is passed to Payfields.button
PayFields.onValidationFailure = function() {
// Enable the button to resubmit
$("#button").prop("disabled", false);
}
// On API error(s), this would handled automatically if an button element is
// passed to Payfields.button
PayFields.onFailure = function() {
// We will flash error response on button
$("#button").text("Error");
$("#button").css(
{"backgroundColor": "rgb(138,15,15)", "transition": "2s"}
);
// Fields are automatically cleared on success. However, We may
// clear all fields, or specific field(s) manually. To clear all fields
// we need to call clearFields without passing any parameter.
PayFields.clearFields();
// To clear one or more fields we need to pass an array to clearfields.
// Possible fields to clear are: number, cvv, expiration, name, and address.
// Payfields.clearFields(['number', 'cvv', 'expiration']);
setTimeout(function() {
$("#button").text("Submit");
$("#button").css(
{"backgroundColor": ""}
);
// Enable button to resubmit
$("#button").prop("disabled", false);
}, 2000);
}
// On Success, display Success and re-enable button
// This would handled automatically if an button element is passed to
// Payfields.button
PayFields.onSuccess = function(response) {
// We will flash success response on button and clear the iframe
// inputs
$("#button").text("Success");
$("#button").css(
{"backgroundColor": "rgb(79,138,16)", "transition": "2s"}
);
setTimeout(function() {
$("#button").text("Submit");
$("#button").css(
{"backgroundColor": ""}
);
$("#button").prop("disabled", false);
}, 2000);
console.log("it was successful");
console.log(response)
}
/*
All available Classes:
'.input' | All fields,
'.number' | Number field,
'.expiration' | Expiration field,
'.cvv' | Cvv field,
'.name' | Name field,
'.address-input' | All address fields,
'.address1' | Address1 field,
'.city' | City field,
'.province' | Province field,
'.postalCode' | Postal Code field,
'.email' | Email field,
'.phone' | Phone field,
'.form-error' | All error spans,
'.number-error' | Number error span,
'.expiration-error' | Expiration error span,
'.cvv-error' | Cvv error span ,
'.name-error' | Name error span,
'.address-form-error' | All Address error spans,
'.address1-error' | Address1 error span,
'.city-error' | City error span,
'.province-error' | Province error span,
'.postalCode-error' | Postal Code error span,
'.email-error' | Email error span,
'.phone-error' | Phone error span
*/
</script>
</body>
</html>
Implementation
The sections below describe how to use PayFields to build a basic payment page:
Include the JavaScript libraries - Include the PayFields and jQuery libraries in the page.
Define the field IDs - Set IDs for each of the fields on the page. PayFields will use the IDs assigned the DIVs to identify where to display the payment fields.
Add the fields to the payment page - Add <div> elements that will contain the fields and assign an ID for the field.
Submit the form data - Call the Payfields.submit() function to send to notify Payrix that the transaction is ready for processing.
Handle the response - Use the PayFields callback functions to notify the customer of the transaction results and provide any necessary followup information.
See the Additional Features documentation for details about implementing the tokenization or auth-only functions offered by PayFields.
Include the JavaScript libraries
PayFields requires the PayFields and the most recent jQuery JavaScript libraries. Add the following code to the <head> section of any page that will use the PayFields scripts:
CODE
<script type="text/javascript" src="https://test-api.payrixcanada.com/payFieldsScript"></script>
<script type="text/javascript" src="https://code.jquery.com/jquery-2.2.4.min.js"></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.
Set the PayFields.config field values in a <script> block to define the following transaction-related options:
Authentication - Set the apiKey and merchant ID values with the PayFields.config.apiKey and PayFields.config.merchant.
Payment Entry Method - If card data will be entered using a card reader, set PayFields.config.swipe to true.
Transaction Amount - Set PayFields.config.amount to the full transaction amount.
Transaction Mode - Set whether the transaction should process a payment, generate a token, or both using the PayFields.config.mode field.
Transaction Type - For auth only transactions, set PayFields.config.txnType to auth. To create a token only, set the PayFields.config.txnType to token.
Define the field IDs
Use the PayFields.fields list to define the IDs that you will use to identify the <div> elements that PayFields will use to display the payment fields. PayFields creates form field elements inside <div> or other elements. You will assign the IDs that you define to each of the <div> element that contains a PayFields element.
The code below shows how to define IDs for the number and cvv types:
CODE
PayFields.fields = [{ type: "number", element: "#number" }, { type: "cvv", element: #cvv }];
Use one of the following values for the type: "number", "cvv", "expiration", "address", "city", "province", "postalCode", "email", "phone".
The element values can be anything you choose, but they must match the IDs you assign to the payment field <div> elements as described in the next section.
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. The example below creates a <div> for the cvv element:
CODE
<div id="#cvv"></div>
PayFields will display the CVV field on the payment page inside the <div> element.
Add a <div> and assign the appropriate ID for each of the payment fields.
When the customer is finished enter data, 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 |
|---|
PayFields.submit();
| Submits the PayFields data to Payrix. |
PayFields.swipePopup();
| Opens the card swipe popup. |
PayFields.clearFields();
| Clears all the values from the fields. |
PayFields.clearFields(["number", "cvv"]);
| Clears the values from the specified fields. |
PayFields.appendTo("number", "#newElement");
| Moves the field to a new DIV. |
PayFields.reload();
| Reappends the PayField with all existing values to the DIV only if the DIV has been removed. |
PayFields.restore();
| Restores the values if PayFields is moved to a new DIV. |
PayFields.button = { element: "#submit", value: "Click to Submit" };
| Displays a button in the specified element for submitting field data to Payrix . |
PayFields.swipeButton = { element: "#swipe", value: "Click to Swipe"};
| Displays a button in the specified element for opening the card swipe popup. |
PayFields.onSuccess = (response) => {};
| Callback function that runs when the API responds with a successful transaction or token. |
PayFields.onValidationFailure = () => {};
| Callback function that runs when validation fails before creating the API call. |
PayFields.onFailure = (response) => {};
| Callback function that runs when the API responds with a failed transaction or token. |
PayFields.onFinish = (response) => {};
| Callback function that runs when the API responds. |
PayFields.onRestore = () => {};
| Callback function that runs when the restore action is run. |
PayFields.config.order = {order number};
| Sets an order number for Level II/III processing. |
PayFields.config.tax = {tax number};
| Sets a tax ID number for Level II/III processing. |
PayFields.config.dicount = {discount number};
| Sets a discount value for Level II/III processing. |
PayFields.config.shipping = {shipping number};
| Sets a shipping number for Level II/III processing. |
PayFields.config.duty = {duty number};
| Sets an duty value for Level II/III processing. |
PayFields.config.items = {items Object};
| Adds an array of items to the order for Level II/III processing. |
PayFields.config.billingAddress = {Billing Object};
| Sets known values of the cardholders billing address without displaying them on the payment page. |
PayFields.config.additionalData = {Additional Object};
| Adds additional data to the order for Level II/III processing. |
PayFields.config.invoiceResult = {Invoice Object};
| Adds an invoice object to the order for Level II/III processing. |
.png)
