Skip to main content
Skip table of contents

PayFrame

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 adds a secure payment submission form to your checkout page. PayFrame creates a seamless customer experience and ensures that all transactions are processed securely and satisfy all PCI requirements. The PayFrame JavaScripts support customization and callback functions, which make it easy to refine the appearance and behavior of the form. The images below show the customer facing payment experience:

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

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

This page includes the information for Partners that want to use PayFrame to add a payment form to a merchant's checkout page:

  • Quickstart - Sample code for creating a basic payment form.

  • Integration - Detailed instructions for adding a payment form to a checkout page.

  • Customization - Descriptions of PayFrame's customization options and how to use them.

Quickstart

To get a basic payment form up and running quickly, copy the code below into an HTML file, add your {API Key} and {Merchant ID} on lines 7 and 8, and open the file in a web browser.

Expand the PayFrame Quickstart Code
HTML 
<!DOCTYPE html>
<head>
    <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/css/bootstrap.min.css" integrity="sha384-Gn5384xqQ1aoWXA+058RXPxPg6fy4IWvTNh0E263XmFcJlSAwiGgFAW/dAiS6JXm" crossorigin="anonymous">
</head>

<body>
  <div class="container">
    <div class="container">
        <div class="row">
            <div class="col-lg-6 offset-3">
            <br>
            <!-- <input class="form-control form-control-sm" placeholder="$0.00" oninput="PayFrame.config.amount = this.value * 100"> -->
            <br>
            <ul class="list-group">
                <li class="list-group-item">
                <button class="btn btn-info btn-sm text-white" id="checkout">Checkout</button>
                </li>
                <li class="list-group-item">
                    <div id="parent-pay"></div>
                </li>
            </ul>
            <div id="responseValue"></div>
            </div> 
        </div>
    </div>
</div>
</body>
</html>

<!-- Include latest stable release of jQuery -->
<script type="text/javascript" src="https://code.jquery.com/jquery-2.2.4.min.js"></script>
<script type="text/javascript" src="https://test-api.payrix.com/payFrameScript"></script>
<script>
    
    PayFrame.config.apiKey = "{{API KEY}}";
    PayFrame.config.merchant = "{{Merchant ID}}";

    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/square_logo.jpg";

    PayFrame.config.button = {
        parent: "parent-pay",
        value: "Pay",
        class: "my-pay"
    };

    PayFrame.config.billingAddress = {
        address: "",
        city: "",
        state: "",
        zip: "",
        email: "",
        phone: ""
    };
    
    /*
    =========================================== 
    Mode
    ===========================================
    PayFrame.config.mode = "txn";
    PayFrame.config.mode = "token"; 
    PayFrame.config.mode = "txnToken"; 
    */

    /*
    =========================================== 
    Transaction Type
    ===========================================
    PayFrame.config.txnType = "sale";
    PayFrame.config.txnType = "auth";
    */

    PayFrame.onSuccess = function (response) {
            // Process the response
        document.getElementById('responseValue').innerHTML = "Success:<br />" + JSON.stringify(response, null, 4);
        }
    PayFrame.onFailure = function (response) {
        // Process the response
        document.getElementById('responseValue').innerHTML = "Failure:<br />" + JSON.stringify(response, null, 4);
    }
    PayFrame.onFinish = function (response) {
        // Process the response
        document.getElementById('responseValue').innerHTML = "Finish:<br />" + JSON.stringify(response, null, 4);
    }

    let checkout = document.querySelector('#checkout');
    checkout.addEventListener('click', function() {
        PayFrame.popup();
    })

</script>

Your {API Key} and {Merchant ID} are available in the Payrix Portal.

Important Info for Canadian Merchants:

  • province fields replace the state fields (see valid values here).

  • postal fields replace zip fields (see valid values here).

  • currency will be in CAD.

Integration

Integrating PayFrame with a merchant's checkout page requires including the PayFrame JavaScript and setting PayFrame configuration values in the payment page’s <head> section. The sections below describe how to create the form, display the form, submitting a transaction, and handle the transaction response.

Create the payment form

Follow the steps below to create a payment form on a merchant's checkout page:

  1. Include the latest version of jQuery and the Payrix's payFrameScript at the top of the page:

    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 by setting the apiKey, merchant, and amount values in a <script> block at the top of the page:

    HTML 
    <script>
  PayFrame.config.apiKey = "b57d7185174957f97b1a4b66350d845b";
  PayFrame.config.merchant = "p1_mer_5a285faf1b79148f3500b9e";
  PayFrame.config.amount = 500;
</script>

    The initialization methods take the following values:

    • apiKey - Your Payrix API key, available in the Payrix Portal

    • merchant - The merchant's identifier on Payrix.

    • amount - The amount in cents that the merchant will charge the customer.

  3. Optional - Prefill the customer's billing address by setting a value for the billingAddress field in the PayFrame <script> block. By default, the payment form prompts the customer for a billing address. Prefilling the address can be more convenient for the customer if the merchant has stored the information. Include the code below in the PayFrame <script> block and set values for each field:

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

Display the payment form

Use a button or a popup to display the form, as described below:

Button

Configure the button in the PayFrame script block, as shown below:

JS 
PayFrame.config.button = {
    parent: "parent-pay",
    value: "Pay",
    class: "my-pay"
  };

Then, assign the parent-pay ID to the parent element that will contain the button object:

HTML 
<div id="parent-pay"></div>

PayFrame will display a button with the label set by the value field in the configuration. The payment form will open when the customer clicks the button.

Popup

To manually display the payment form, call the popup method. You can call the popup method along with the configuration scripts, as shown below, or use any other technique to trigger it:

JS 
PayFrame.popup()

Submit the transaction

The payment form includes a "Submit" button that securely sends transaction information to Payrix for processing. When processing is complete, Payrix returns the response using on of the callback functions defined in the next section.

Handle the response

PayFrame returns transaction results using one of the following callback functions:

  • onSuccess - Executes if the transaction is successful. Display a purchase confirmation on the merchant's site and process the order as normal.

  • onFailure - Executes if the payment fails. Display a failure notification on the merchant's site and correct the payment or cancel the order.

  • onFinish - Executes whether the transaction succeeds or fails.

Add the code below to the <script> block with the rest of the PayFrame scripts. Then update the functions to work with the merchant's checkout page:

JS 
PayFrame.onSuccess = function (response) {
    // Process the responsePayFrame.config.billingAddress = {
  }
  PayFrame.onFailure = function (response) {
    // Process the response
  }
  PayFrame.onFinish = function (response) {
    // Process the response
  }

Customization

PayFrame supports the following customization options:

  • color - Sets the background color for header and button elements on the form.

  • 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, that will be displayed on the form.

Add the code below to the <script> block that contains the rest of the PayFrame functions. Then update the values to match the merchant's requirements:

JS 
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";>

JavaScript errors detected

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

If this problem persists, please contact our support.

Contact Support Close