Skip to main content
Skip table of contents

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:

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

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.

    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.

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

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

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

HTML
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:

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

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

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

Setup Parameter

Description

Example Value

PayFrame.config.apiKey

API key for authentication with Payrix services

ab123c4def5g6hijkl7890m12345no6p

PayFrame.config.merchant

Merchant ID for identification and routing of transactions.

t1_mer_123ab4c567defg8h90123i45

PayFrame.config.amount

Transaction amount to be processed.

500

PayFrame.config.txnType

Type of transaction to be performed (e.g., 'sale', 'auth').

'sale'

PayFrame.config.billingAddress = {}

Customer's billing address details for prefilling the form.

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

address

Customer’s address

"123 Main Street"

city

Customer’s city

"New York"

state

Customer’s state or province

"NY"

zip

Customer’s postal code

"10001"

email

Customer’s email address

"customer@examplemail.com"

phone

Customer’s phone number

"555-555-5555"

PayFrame.config.button = {}

Configuration for displaying a button to open the payment form

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

parent

The ID of the <div> assigned to the PayFrame button.

parent: "#submitPayment"

value

PayFrame button label.

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.

Display Action

PayFrame JS Configuration

Description

Displaying the Form

PayFrame.popup

Configures a button, calling the popup method to display the payment form for customers to complete transactions.

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.

Response

PayFrame JS Configuration

Description

Successful Payment

PayFrame.config.onSuccess

Defines the next action following a successful payment response from the PayFrame service.

Failed Payment

PayFrame.config.onFailure

Defines the next action following a failed payment response from the PayFrame service.

Validation Failure

PayFrame.config.onValidationFailure

Defines the next action following a PayFrame error being returned returns an error.

Completed Transaction

PayFrame.config.onFinish

Defines the next action following a completed transaction response, whether the transaction succeeds or fails, from the PayFrame service.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.