PayFrame Integration Guide
PayFrame embeds a Payrix-hosted payment form on a merchant’s checkout page. PayFrame includes basic customization options and requires minimal development effort to implement.
PayFrame integrates a secure payment submission form into your checkout page, enhancing customer experience and guaranteeing secure transaction processing that meets all PCI requirements. With customizable JavaScript and callback functions, PayFrame allows effortless adjustments to the form's appearance and functionality.
Shown below are images showcasing the customer payment experience:
Getting Started
This page includes the information for Partners that want to use PayFrame to add a payment form to a merchant's checkout page:
Integrating PayFrame with a merchant's checkout page involves several steps to ensure a seamless payment experience. Below is a detailed guide on how to create the payment form, display it, submit a transaction, and handle the transaction response effectively.
Below you’ll initialize the payment form, display the payment form, customize its appearance, and finally handle the actions of your webpage following varying responses.
Initialize the Payment Form
To create a payment form on a merchant's checkout page, follow these steps:
Add jQuery and PayFrame Libraries: Start by including the latest version of jQuery and Payrix's PayFrame Script at the top of the page. This ensures that the necessary libraries are available for the integration process.
<!-- Include latest stable release of jQuery --> <script type="text/javascript" src="https://code.jquery.com/jquery-2.2.4.min.js"></script> <!-- Include the PayFrame JavaScript --> <script type="text/javascript" src="https://api.payrix.com/payFrameScript"></script>
Initialize PayFrame: Set the
apiKey
,merchant
,amount
, andtxnType
values in a<script>
block at the top of the page to initialize PayFrame. These values are crucial for the proper functioning of the payment form.<script> PayFrame.config.apiKey = "ab123c4def5g6hijkl7890m12345no6p"; // Required PayFrame.config.merchant = "t1_mer_123ab4c567defg8h90123i45"; // Required PayFrame.config.amount = 500; // Required PayFrame.config.txnType = 'sale'; // Required. </script>
Optional Billing Address: To prefill the customer's billing address, set values for the
billingAddress
field in the PayFrame<script>
block. This step enhances convenience for customers if their information is already stored.PayFrame.config.billingAddress = { address: "123 Main Street", city: "New York", state: "NY", zip: "10001", email: "customer@examplemail.com", phone: "555-555-5555" };
Display the Payment Form
Now that you’ve successfully initialized the PayFrame payment form with the required library frameworks, PayFrame configurations, and optionally the billing address, you can now configure how and when the PayFrame payment form is displayed using the configuration steps below:
Button
With the button option, you can display the PayFrame payment form on-click, making the checkout experience controlled by the customer.
Button (Manual)
Configure the button within the PayFrame script block to display a button that opens the payment form when clicked.
Assign the submitPayment
ID to the parent element that will contain the button object.
Popup (Automated)
To display the PayFrame payment form automatically or based on the result of another function on your webpage, you can utilize the Popup option to trigger the payment form as needed and have maximum control over the customer’s checkout experience and flow.
To manually display the payment form, call the popup
method along with the configuration scripts. This method allows you to trigger the payment form display as needed.
Submitting the Transaction
The PayFrame library provides an embedded "Submit" button displayed on the payment form to securely send transaction information to the platform for processing via the Merchant’s credentials (API Key and Merchant ID).
Customize the Payment Form
PayFrame offers customization options to tailor the payment form to meet specific merchant requirements:
color
: Sets the background color for the heading and submit transaction button.name
: Sets the primary text displayed in the form header.description
: Sets the secondary text displayed in the form header.image
: Sets an image, such as a merchant’s logo, to be displayed on the form.
Integrate the following code snippet into the <script>
block to customize the PayFrame according to the merchant's branding:
Handling Payment Form Responses
PayFrame provides callback functions to handle transaction responses effectively:
onSuccess
: Executes if the transaction is successful.onFailure
: Executes if the payment fails.onFinish
: Executes whether the transaction succeeds or fails.
Ensure to update these functions to work seamlessly with the merchant's checkout page.
Completed Integration Example
Preview the consolidation of all the steps displayed above into a full webpage with a PayFrame payment form integration.
Tip: If you haven't set up a PayFrame integration on your website, copy the code snippet below. Adjust the setup parameters and customization values to fit your business needs.
PayFrame Configuration Parameters
Here is a table summarizing the JavaScript parameters, stylization values, actions, and required parameters to set up PayFrame for seamless integration:
Setup Parameters
By utilizing the setup parameters outlined in PayFrame.config, you can securely authenticate the Merchant using their ID and API Key (or txnSession Key depending on your configuration). Subsequently, you will then establish the transaction amount and type (Sale or Auth) through other necessary parameters, while also specifying a billing address for the cardholder and linking the button to the designated PayFrame pop-up function.
Setup Parameter | Description | Example Value | |
---|---|---|---|
| API key for authentication with Payrix services |
| |
| Merchant ID for identification and routing of transactions. |
| |
| Transaction amount to be processed. |
| |
| Type of transaction to be performed (e.g., 'sale', 'auth'). |
| |
| Customer's billing address details for prefilling the form. | ||
 |
| Customer’s address |
|
| Customer’s city |
| |
| Customer’s state or province |
| |
| Customer’s postal code |
| |
| Customer’s email address |
| |
| Customer’s phone number |
| |
| Configuration for displaying a button to open the payment form | ||
 |
| The ID of the |
|
| PayFrame button label. |
|
Customization Options
Customize your current PayFrame by utilizing the following configurations. Opt to pre-fill and hide the Billing Address input fields for the transaction to simplify the cardholder checkout process. Additionally, you can enhance the PayFrame popup by including a name & description, and personalize the cardholder journey by choosing the background color and logo image.
Customization | PayFrame JS Configuration | Description |
---|---|---|
Name |
| The title that appears at the top of the PayFrame pop-up form. |
Description |
| The description that appears in the PayFrame pop-up form. |
Hide Billing Address Input |
| Option to hide billing address fro the PayFrame form, particularly useful for pre-filled address information. |
Background Color |
| The primary background color of the PayFrame pop-up form heading and button elements. Uses Hex Code format. |
Image |
| The logo displayed on the PayFrame pop-up form. Retrieves Image via URL. |
Manually Displaying the Form
Utilize the PayFrame library's custom JavaScript function to trigger the appearance of the PayFrame payment form popup on the screen manually rather than through the automated process when the assigned button is clicked by the cardholder.
Display Action | PayFrame JS Configuration | Description |
---|---|---|
Displaying the Form |
| Configures a button, calling the |
Response Options
Ensure to follow these guidelines to effectively set up and customize PayFrame for a seamless payment experience.
Response Handling
Using the response handling options, you can tailor your customer’s journey, and delight with features of your webpage UI, such as displaying a success message or checkmark for successful payments; a troubleshooting message advises trying a different payment method for failed payments, and a completed transaction response removing the payment form and providing a seamless checkout experience.
Response | PayFrame JS Configuration | Description |
---|---|---|
Successful Payment |
| Defines the next action following a successful payment response from the PayFrame service. |
Failed Payment |
| Defines the next action following a failed payment response from the PayFrame service. |
Validation Failure |
| Defines the next action following a PayFrame error being returned returns an error. |
Completed Transaction |
| Defines the next action following a completed transaction response, whether the transaction succeeds or fails, from the PayFrame service. |