{{glossary.PayFrame}} embeds a {{glossary.Payrix Pro}} platform-hosted payment form on a {{glossary.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 {{glossary.transaction}} processing that meets all PCI requirements. With customizable JavaScript and callback functions, PayFrame supports effortless adjustments to the form's appearance and functionality.

Shown below are images showcasing the customer payment experience:

Payment form displaying card details, including card number, expiration date, and CVV.

Payment information form with fields for address, email, and total amount due.

Getting Started

This page includes the information for {{glossary.Partner}} 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 the Payrix Pro 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, 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>

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.

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

Make sure 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

Below is a table summarizing the JavaScript parameters, stylization values, actions, and required parameters to set up PayFrame for seamless integration.

Setup Parameters

By using 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 Pro platform 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 (such as 'sale' or 'auth')	`'sale'`
`PayFrame.config.billingAddress = {}`		Customer's billing address details for prefilling the form	`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	`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 using 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 and description, and you can 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 from 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

Use 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

Make sure 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 with features of your webpage UI, such as displaying a success message or checkmark for successful payments, a troubleshooting message that 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

Integrated Payment Pages