Introduction

The TransactionAPI is a RESTful API for interfacing with the Gateway. The API includes familiar transaction types from the BridgeComm API in a user friendly JSON interface.

Key Elements

The Transaction API request and response structure is made up of a core set of data elements plus specific objects and their sub-elements. Each object handles a subsection of API data elements like payment data, Healthcare, or Level II/III information elements. The core data elements are within the main request body and will include basic information like accountType, holderType, and transactionType.

A list of all required and optional data elements can be found in each section.

In the live environment, transactions must be initiated over an SSL-protected connection using a minimum of 128-bit encryption to protect sensitive data. Initial testing can be performed over an unencrypted connection; however, testing must be performed over an SSL-encrypted channel before a client can be certified to production. Only test card/ACH account data may be transmitted. No live payment information should ever be transmitted to the test system.

Timeouts

The Transaction API has an internal timeout of 100 seconds. Integrating applications can expect all transactions to take less than 100 seconds, and if 100 seconds are exceeded without a response from the Transaction API, you may close your connection. If a transaction as attempted leveraging an invoiceNumber, you may use a Find Transaction request using your unique invoiceNumber to confirm the outcome of the transaction.

Authentication Information

Each call to the Transaction API requires credentials; however, these credentials are not submitted in the request body. The username and password are values created in MyBridgePay, and they will be submitted in the request headers as Basic HTTP authentication.

The Credentials object is used as a property of other objects in the API. The Credentials Object contains two properties: username and password.

Overview

The TokenPay.js provides users to securely collect card information and execute transaction in a PCI compliant manner. The base integration solutions for TokenPay.js include:

• TransactionAPI - a web services API for payment processing. The use of Transaction API (without TokenPay.js) for payment capture places 100% of PCI Compliance responsibility on the Customer's integration
• TokenPay.js - is an extension of the Transaction API that combines client-side and server-side technologies for PCI-compliant online payment capture.

TokenPay.js maximizes the user experience by allowing for the capture of sensitive card data within the payment form on the merchant's website. The consumer remains on the merchant's payment page at all times. The payment ‘token’ is only valid for use within 15 minutes of being generated or until used for the Transaction API transaction.

TokenPay.js is an integration interface for the Payment Gateway that primarily facilitates online card payments in a manner that ensures that no sensitive card data ever needs to reach your servers so your integration can operate in a PCI compliant way.

To ensure that merchants are eligible for the simplest PCI validation method, Self-Assessment Questionnaire (SAQ A)*, TokenPay.js utilizes:

• Isolation - Payment Gateway hosts the card sensitive data input fields. The fields are injected into your form as an HTML iframe thus isolating your page and your server from card sensitive data.
• Tokenization - in order to execute transactions against the user's card, TokenPay.js tokenizes the card sensitive data. The card token is generated via the use of the TokenPay.js JavaScript library and your payment form.
• Public/Private Keys - The injection of the TokenPay.js hosted input fields and card tokenization is authenticated via a public key assigned to the merchant. API requests to execute charges against the tokenized card information are made by the backend server and are authenticated with a private key assigned to the merchant.
• If you are processing more than six million transactions per year, you are not eligible to use a SAQ to prove PCI compliance. Payment brands require you to complete a Report on Compliance (RoC) to validate your PCI compliance annually.

Authentication

TokenPay.js transactions will not use Basic Authorization like other transaction types in the Transaction API. To authenticate a TokenPay.js transaction, Basic Authorization must be disabled and an Authorization header must be included.

The Authorization header value is a combination of a static text value (TokenPay) and a base64 encoded combination of the AuthenticationTokenID and the TokenPay.js PrivateKey separated by a colon (:). Examples of how this is achieved are provided in this collection, and the process for compiling is exemplified in the pre-request script for these examples.

Below is an example of the raw and Base64 encoded values:

• RAW: TokenPay f5021ddf-afe1-4db6-961c-a65185e79d13:TtXNMYZUXRSZWfw4
• Base64: TokenPay ZjUwMjFkZGYtYWZIMS00ZGI2LTk2MWMtYTY1MTg1ZTc5ZDEzOIR0WE5NWVpVWFJTWIdmdzQ=

Client Side

TokenPay.js is the JavaScript library for building payment flows within the Payment Gateway. With it you can collect card sensitive data from the user and create payment tokens for securely sending the data to your server in a PCI compliant manner.

TokenPay.js provides a ready-made UI component for collecting the card sensitive data from the user. TokenPay.js then tokenizes the information without ever having to touch your server.

The TokenPay.js UI component includes:

• Automatically format card information as it is entered
• Validation of card information as it is entered
• Responsive Design that works on user's screen or mobile device
• Customizable styling to match your look and feel

Payment Form Submission Best Practices

When implementing payment forms, it is recommended that the integrator utilize reCAPTCHA. reCAPTCHA protects payment forms from SPAM and bot abuse. Using reCAPTCHA on your payment forms reduces the risk of fraudulent transactions on the merchant's eCommerce sites by performing a Completely Automated Public Turing Test to Tell Computers and Humans Apart (CAPTCHA) test to tell humans and bots apart.

For more information on reducing form SPAM and bot abuse visit: https://developers.google.com/recaptcha/intro

Public and Private Keys

When a Payment Gateway Merchant using the Transaction API wants to utilize TokenPay.js for online transactions, a public/private key pair is assigned to the merchant for use with TokenPay.js. The public/private key is tied to a merchant account and merchant account code combination.

The public key is utilized by the TokenPay.js JavaScript library on your payment web page and is publicly visible, but this key only allows for the injection of the Payment Gateway hosted input fields. This key cannot be used to execute transactions against the user's card.

The private key MUST be secured and never shared. The combination of the TokenPay.js generated card payment token and private key allows for charges to be made against the associated user's card.

HTTP Requirements

All submission of payment information using TokenPay.js is made via a secure HTTPS connection. To protect yourself from man-in-the-middle attacks and to prevent your users from experiencing mixed content warnings in their browser, you MUST server the page with your payment form over HTTPS.

The URL of the page containing TokenPay.js MUST begin with https://

< Test URL >

https://rhuat.bridgepaynetsecuretest.com/WebSecurity/TokenPay/plain-js/tokenPay.js

< Production URL >

https://api.rectanglehealth.com/WebSecurity/TokenPay/plain-js/tokenPay.js

Step 1: Setting Up TokenPay.js

To get started, include this script on your page (sample code is using the Test URL):

<html>
<head>
   <title>Payment</title>
   <script type="text/javascript" src="https://www.bridgepaynetsecuretest.com/WebSecurity/TokenPay/plain-js/tokenpay.js"></script>
   <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css" integrity="sha384-BVYiiSIFeK1dGmJRAkycuHAHRg32OmUcww7on3RYdg4Va+PmSTsz/K68vbdEjh4u" crossorigin="annoymous">
   <style>
       #amount {
           width: 75px;
       }
   </style>
</head> <html>
<head>
   <title>Payment</title>
   <script type="text/javascript" src="https://www.bridgepaynetsecuretest.com/WebSecurity/TokenPay/plain-js/tokenpay.js"></script>
   <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css" integrity="sha384-BVYiiSIFeK1dGmJRAkycuHAHRg32OmUcww7on3RYdg4Va+PmSTsz/K68vbdEjh4u" crossorigin="annoymous">
   <style>
       #amount {
           width: 75px;
       }
   </style>
</head>

Step 2: Create Your Payment Form

To securely collect card sensitive details from your users, TokenPay.js creates UI components for you that are hosted by gateway. They are then inserted into your payment form.

To determine where to insert the UI components, create empty DOM elements with unique IDs within your payment form. If you want to modify and customize the style of the card entry area, create a hidden element to contain your styling. The id of this element MUST be ‘customStyles’.

<body>
<form id="paymentForm" action="rhuat.bridgepaynetsecuretest.com/WebSecurity/echo.aspx" method="post" style="margin: 10px">
    <select class="form-control" name="amount" id="amount" style="width:100px;">
         <option value="25">$25</option>
         <option value="50">$50</option>
    </select>
    <div id="card" style="border: solid 1px red; min=height: 200px; width: 470px; padding: 20px 10px; border-radius: 10px; margin: 10px 0px;"></div>
    <div id="errorMessage" style="margin-bottom: 10px; color: #c0392b;"></div>
    <button type="submit" class="btn btn-default">Submit</button>
</form> <body>
<form id="paymentForm" action="rhuat.bridgepaynetsecuretest.com/WebSecurity/echo.aspx" method="post" style="margin: 10px">
    <select class="form-control" name="amount" id="amount" style="width:100px;">
         <option value="25">$25</option>
         <option value="50">$50</option>
    </select>
    <div id="card" style="border: solid 1px red; min=height: 200px; width: 470px; padding: 20px 10px; border-radius: 10px; margin: 10px 0px;"></div>
    <div id="errorMessage" style="margin-bottom: 10px; color: #c0392b;"></div>
    <button type="submit" class="btn btn-default">Submit</button>
</form>

When the form is loaded, initialize the Pay element:

• Replace the phrase your-public-key, shown below, with your publishable public key tied to your merchant account and merchant account codes.
• To display ACH instead of credit card fields set ‘eACH’ to ‘true’.
• To disable zip code field (prevent zip code field from displaying) set ‘disableCVV’ to ‘true’

<script>
   var tokenpay = TokenPay('tokenpay22725api20250527120554796');
   tokenpay.initialize({
        dataElement: ‘card’,
        errorElement: ‘errorMessage’,
        amountElement: ‘amount’,
        useACH: false,
        useStyles: false,
        disableZip: false,
        disableCvv: false
    });
     <script>
   var tokenpay = TokenPay('tokenpay22725api20250527120554796');
   tokenpay.initialize({
        dataElement: ‘card’,
        errorElement: ‘errorMessage’,
        amountElement: ‘amount’,
        useACH: false,
        useStyles: false,
        disableZip: false,
        disableCvv: false
    });

The TokenPay element simplifies the form and minimizes the fields required by inserting a single input field that securely collects all needed card data.

If you have created the customStyles element to style the card entry area, change the value of ‘useStyles’ to ‘true’.

Step 3: Submit the Token

The card data collected by the TokenPay element returns a payment token to be used with the private key for the transaction request to the Transaction API. If there are any errors in the collection of the card data or creation of the payment token, information is automatically displayed in the ‘errorElement’ of your payment form.

var form = 
document.getElementById
('paymentForm);
    
form.addEventListener
('submit', function(event) {
        event.preventDefault();
        tokenpay.createToken(function (result) {
            var hiddenInput = document.createElement('input');
            hiddenInput.setAttribute('type', ‘hidden’);
            hiddenInput.setAttribute('name', ‘token’);
            hiddenInput.setAttribute('value', result.token);
            form.appendChild(hiddenInput);
            form.submit();
        }, function (result) {
            console.log("error: " + result);
        });
    });
</script>
</body>
</html> var form =
document.getElementById
('paymentForm);

form.addEventListener
('submit', function(event) {
        event.preventDefault();
        tokenpay.createToken(function (result) {
            var hiddenInput = document.createElement('input');
            hiddenInput.setAttribute('type', ‘hidden’);
            hiddenInput.setAttribute('name', ‘token’);
            hiddenInput.setAttribute('value', result.token);
            form.appendChild(hiddenInput);
            form.submit();
        }, function (result) {
            console.log("error: " + result);
        });
    });
</script>
</body>
</html>

Server Side

Once you have securely collected and tokenized your user's card payment data using TokenPay.js, you will have a 15 minutes window in which to complete the transaction request. The payment token expires after the 15 minutes window or when used.

To complete the transaction, you must perform a sale, validation or multi-use token request in a call to the Transaction API.

Overview

PayGuardian Cloud is a web-based hosted service used to interact with EMV devices for securely processing transactions with your Point of Sale. The RESTful API allows for easy interactions via simple JSON requests.

Highlights include:

• Hosted web services gives you the ability to POST a transaction request to any terminal at any location

• Automated network discovery establishes and maintains a persistent connection to the gateway

• Multiple registers and credit card terminals can be used simultaneously

• Automates updates-no software installation necessary

• PA-DSS compliant & TLS 1.2

• No access to sensitive card data

Connection Strings

< TEST >

The mode key should always be set to UAT when POSTing to this URL.

< PRODUCTION >

The mode key should always be set to PROD when POSTing to this URL

Key Elements

Prerequisites

Before continuing, you should have test merchant account credentials and a Cloud certified device.

Devices

Terminals intended for use in production must be injected with the Production Rectangle Health P2PE key.
Terminals intended for use in UAT must be injected with the Test Rectangle Health P2PE key. Please reach out to Payments (payments@rectanglehealth.com) for key
information.

< PAX >

PAX A Series devices are WiFi enabled and complete the same integration process for PG Cloud. The A Series requires a download of the PayGuardian Cloud Mobile App from the PAXStore to load onto the device. For PAXStore access or app related issues, please email [paxstore.support@pax.us](mailto: paxstore.support@pax.us). PAX requires anyone using their device to be registered with the PAXStore.

The following PAX A Series devices are currently supported:

• A920 Max

• A80

• A800

< Ingenico >

Ingenico Tetra Lane devices are ethernet based processing terminals and require basic configuration to install PayGuardian Cloud.
The following Ingenico Tetra Series devices are currently supported.

• Lane 3000

• Lane 7000

Process Flow

PayGuardian Cloud acts as middleware to save the integrator from interfacing directly with the device itself. The process flow is a simple request and response; however, the request
will trigger the device to prompt for the card and process the transaction.
Once the transaction is processed, the response data is fed back up the chain to the gateway and the integrated POS system.

Authentication Information

Each request to PayGuardian cloud requires credentials to authorize. These values are defined in full in the Request and Response information section, and they are listed below:

• username

• password

• merchantAccountCode

• merchantCode

Introduction

This API provides the ability to create and manage user and TokenPay credentials.

Authentication

Each call to the Credentials Management API requires credentials. The Credentials object is used as a property of other objects in the API. The Credentials Object contains two properties: UserName and Password.

Both properties are strings.