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:

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.

   HTML

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

   HTML

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

   HTML

   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.

PayFrame.config.button = {
    parent: "#submitPayment",
    value: "Pay Now",
};

Assign the submitPayment ID to the parent element that will contain the button object.

<div id="submitPayment"></div>

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.

PayFrame.popup()

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:

PayFrame.config.color = "86C6D0";
PayFrame.config.name = "Demo Name";
PayFrame.config.description = "This is a Demo";
PayFrame.config.image = "<http://example.com/images/square_logo.jpg";>

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.

PayFrame.onSuccess = function (response) {
    // Process the response
}
PayFrame.onFailure = function (response) {
    // Process the response
}
PayFrame.onFinish = function (response) {
    // Process the response
}

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.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>PayFrame Integration</title>
    <!-- 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>
    <style>
        .container {
            max-width: 600px;
            margin: 50px auto;
            padding: 20px;
            border: 1px solid #ccc;
            border-radius: 5px;
            background-color: #f9f9f9;
        }

        .button {
            background-color: #17a2b8;
            color: white;
            padding: 10px;
            border: none;
            border-radius: 5px;
            cursor: pointer;
            width: 100%;
            text-align: center;
        }

        .list-item {
            margin-bottom: 10px;
            padding: 10px;
            border: 1px solid #ccc;
            border-radius: 5px;
            background-color: white;
        }

        #responseValue {
            margin-top: 20px;
            padding: 10px;
            background-color: #e9ecef;
            border-radius: 5px;
        }
    </style>
</head>

<body>
    <div class="container">
        <div class="list-item">
            <div id="submitPayment"></div>
        </div>
        <div id="responseValue"></div>
    </div>
    <script>
        PayFrame.config.apiKey = 'ab123c4def5g6hijkl7890m12345no6p'; // Required.
        PayFrame.config.merchant = 't1_mer_123ab4c567defg8h90123i45'; // Required.
        PayFrame.config.name = "Title";
        PayFrame.config.description = "Description";
        PayFrame.config.hideBillingAddress = false;
        PayFrame.config.amount = 1725;
        PayFrame.config.color = "86C6D0";
        PayFrame.config.image = "http://example.com/images/logo.jpg";
        PayFrame.config.button = {
            parent: "parent-pay",
            value: "Pay",
            class: "my-pay"
        };
        PayFrame.config.billingAddress = {
            address: "",
            city: "",
            state: "",
            zip: "",
            email: "",
            phone: ""
        };
        PayFrame.onSuccess = function (response) {
            document.getElementById('responseValue').innerHTML = "Success:<br />" + JSON.stringify(response, null, 4);
        };
        PayFrame.onFailure = function (response) {
            document.getElementById('responseValue').innerHTML = "Failure:<br />" + JSON.stringify(response, null, 4);
        };
        PayFrame.onFinish = function (response) {
            document.getElementById('responseValue').innerHTML = "Finish:<br />" + JSON.stringify(response, null, 4);
        };
        document.getElementById('submitPayment').addEventListener('click', function () {
            PayFrame.popup();
        });
    </script>
</body>
</html>

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.

PayFrame.config.billingAddress = { 
  address: "", 
  city: "", 
  state: "",
  zip: "",
  email: "",
  phone: ""
}

PayFrame.config.button = { 
  parent: "#submitPayment", 
  value: "Pay Now", 
}

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	PayFrame.config.name	The title that appears at the top of the PayFrame pop-up form.
Description	PayFrame.config.description	The description that appears in the PayFrame pop-up form.
Hide Billing Address Input	PayFrame.config.hideBillingAddress	Option to hide billing address fro the PayFrame form, particularly useful for pre-filled address information.
Background Color	PayFrame.config.color	The primary background color of the PayFrame pop-up form heading and button elements. Uses Hex Code format.
Image	PayFrame.config.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.

Note: Manually calling PayFrame.popup is recommended for streamlining the timing of the payment form with other elements or processes on your webpage, like a cart checkout flow.

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.