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:

Open

The customer enters payment info and clicks the Billing Address button.

Open

The customer enters the billing address and clicks the PAY button.

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:

1. 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>

2. Initialize PayFrame: Set the apiKey, merchant, amount, and txnType 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>

3. 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.

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.

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.

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.

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.