NAV Navbar

Beyond Pay Gateway

GET /BeyondPay
Pricing: Transparent, Protected
Integration: Easy
Security: World-Class
Service: Top-Notch

Get your API keys and get coding now!

Contact us if you have questions or need any help! BeyondPayIntegrations@getbeyond.com

Welcome to the Beyond Pay Gateway API! Beyond Pay is a powerful payment gateway that enables you to securely accept many different payment types. Plus, by processing through Beyond Pay, you support the philanthropic cause at the heart of Beyond's mission!

The primary integration options offered by the Beyond Pay platform include:

Online Payments

Getting Started

To get started, include these scripts on your checkout page:

<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.3.1/jquery.min.js"></script> 
<script
  src="https://api-test.getbeyondpay.com/Bridgepay.WebSecurity/TokenPay/js/tokenPay.js">
</script>

Next, create an instance of TokenPay:

var tokenpay = TokenPay('your-public-key');

Replace your-public-key with your publishable public key.

TokenPay captures the sensitive card data within the payment form of your website. The consumer remains on your payment page at all times during the checkout process, reducing potential shopping cart abandonment.

TokenPay is an integration interface for Beyond Pay Gateway which facilitates online card payments in a manner that ensures that no sensitive card data ever touches your servers so your integration can operate with minimized scope of PCI.

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

TokenPay.js

Sandbox Script (Testing):

https://api-test.getbeyondpay.com/Bridgepay.WebSecurity/TokenPay/js/tokenPay.js

Live Script (Production):

https://api.getbeyondpay.com/WebSecurity/TokenPay/js/tokenPay.js

TokenPay.js is the JavaScript library for building online or mobile browser checkout flows with Beyond Pay Gateway. With it, you can collect sensitive data from the cardholder and create tokens for securely sending the data to your webserver.

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

The TokenPay.js UI component includes:

HTTPS Requirements

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

Create a Payment Form

To determine where to insert the UI components, create empty DOM elements with unique IDs within your payment form.

<form id="paymentForm" action="/charge" method="post"> 
  <select class="form-control" name="amount" id="amount">
    <option value="25">$25</option>
    <option value="50">$50</option> 
  </select>
  <div id="card"></div>
  <div id="errorMessage"></div>
  <button type="submit">Submit</button>
</form>

If you want to customize the style of the card entry area, create a hidden <div> element to contain your styling. The id of this element MUST be customStyles.

<div style="display: none" id="customStyles"> 
  body {
    margin: 8px 0;
    }
#payment-form {
  border: 2px solid #003b5c; 
  padding: 5px 10px; 
  border-radius: 5px; 
  background: white;
  color: #333;
}
</div>

When the form is loaded, initialize the Pay element:

tokenpay.initialize({
  dataElement: '#card', 
  errorElement: '#errorMessage', 
  useStyles: false
});

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

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

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

Obtain a Single-Use Token

var form = document.getElementById('paymentForm'); 
$('#paymentForm').on('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);
  });
});

The card data collected by the TokenPay element is posted from the client browser to Beyond Pay Gateway where it is converted into a single-use token. If there are any errors in the collection of the card data or creation of this token, information is automatically displayed in the errorElement of your payment form.

The token is stored as a hidden input value and passed to your server on form submission.

Charge the Single-Use Token

With the token and other key form fields obtained, now construct the XML payload from your server application:

<requestHeader>
    <ClientIdentifier>SOAP</ClientIdentifier>
    <TransactionID>{transactionId}</TransactionID>
    <RequestType>004</RequestType>
    <RequestDateTime>{requestDateTime}</RequestDateTime>
    <PrivateKey>{yourPrivateKey}</PrivateKey>
    <AuthenticationTokenId>{token}</AuthenticationTokenId>
    <requestMessage>                                        
        <SoftwareVendor>{yourSoftwareName}</SoftwareVendor>
        <TransIndustryType>EC</TransIndustryType>
        <TransactionType>sale</TransactionType>
        <AcctType>R</AcctType>
        <HolderType>O</HolderType>
        <Amount>{amountInCents}</Amount>
        <CurrencyCode>USD</CurrencyCode>
    </requestMessage>
</requestHeader>

Encode the XML payload in Base-64 and package it within a SOAP envelope:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:req="http://bridgepaynetsecuretx.com/requesthandler">
                    <soapenv:Header/>
                        <soapenv:Body>
                            <req:ProcessRequest>
                                <req:requestMsg>{Base-64 encoded XML payload}</req:requestMsg>
                            </req:ProcessRequest>
                        </soapenv:Body>
                    </soapenv:Envelope>

POST the SOAP envelope to the appropriate endpoint:

Sandbox (Testing):

https://api-test.getbeyondpay.com/PaymentService/RequestHandler.svc

Live (Production):

https://api.getbeyondpay.com/PaymentService/RequestHandler.svc

Once you have securely collected and tokenized your user’s card data using TokenPay.js you can now use the single-use token to submit a transaction. Authorization or sale requests using single-use tokens must ONLY made from your server and not from the client.

On your server application, collect the token information and the form POST parameters submitted by your form.

Now submit the token and parameters according to the example XML request, with the following substitutions:

After your transaction has been successfully submitted to the gateway, make sure you parse and inspect the response message. Specifically, look at:

"Auth-Only" or "Pre-Auth"

To change from a "sale" transaction to an "authorize" transaction, simply set TransactionType to sale-auth:

<requestHeader>
    <ClientIdentifier>SOAP</ClientIdentifier>
    <TransactionID>{transactionId}</TransactionID>
    <RequestType>004</RequestType>
    <RequestDateTime>{requestDateTime}</RequestDateTime>
    <PrivateKey>{yourPrivateKey}</PrivateKey>
    <AuthenticationTokenId>{token}</AuthenticationTokenId>
    <requestMessage>                    
        <SoftwareVendor>{yourSoftwareName}</SoftwareVendor>
        <TransIndustryType>EC</TransIndustryType>
        <TransactionType>sale-auth</TransactionType>
        <AcctType>R</AcctType>
        <HolderType>O</HolderType>
        <Amount>{amountInCents}</Amount>
        <CurrencyCode>USD</CurrencyCode>
        <SettlementDelay>{daysToDelay}</SettlementDelay>
    </requestMessage>
</requestHeader>

In order to actually capture that authorization and charge the card, you must submit 019 capture RequestType, passing the original sale-auth GatewayTransId in the 'ReferenceNumber' field, and using the User and Password credentials instead of AuthenticationTokenId and PrivateKey to authenticate:

<requestHeader>
    <ClientIdentifier>SOAP</ClientIdentifier>
    <TransactionID>{transactionId}</TransactionID>
    <RequestType>019</RequestType>
    <RequestDateTime>{requestDateTime}</RequestDateTime>
    <User>{Beyond-assigned username}</User>
    <Password>{Beyond-assigned password}</Password>
    <requestMessage>
        <SoftwareVendor>{yourSoftwareName}</SoftwareVendor>
        <TransactionType>capture</TransactionType>
        <ReferenceNumber>{original sale-auth GatewayTransId from response}</ReferenceNumber>
        <Amount>{amountInCents}</Amount>
    </requestMessage>
</requestHeader>

Sometimes you may not want to accept payment right away for a transaction, such as when shipping physical goods. The normal practice in this scenario is to first authorize a card which will place a hold on the funds, and then to later "capture" that authorization when the order is fulfilled.

The SettlementDelay tag can be added for sale-auth transactions, and designates the number of batch cycles that the authorization remains "open" (or unsettled). If the sale-auth transaction is not captured before completion of the designated number of batches, then the original authorization will be automatically voided and not captured.

To capture an authorization (sometimes called a "pre-auth"), simply submit a RequestType of 019 for capture, along with passing the reference number of the original authorization as shown here.

Repeat Sales and Cards-on-File

The Token element represents a card number and is valid so long a the card is valid. It may be used as input in a transaction in lieu of the PaymentAccountNumber or the AuthenticationTokenId, and also requires the ExpirationDate field to be submitted with it.

<requestHeader>
    <ClientIdentifier>SOAP</ClientIdentifier>
    <TransactionID>{transactionId}</TransactionID>
    <RequestType>004</RequestType>
    <RequestDateTime>{requestDateTime}</RequestDateTime>
    <User>{Beyond-assigned username}</User>
    <Password>{Beyond-assigned password}</Password>
    <requestMessage>
        <SoftwareVendor>{yourSoftwareName}</SoftwareVendor>                    
        <Token>{token - not to be confused with AuthenticationTokenId}</Token>
        <ExpirationDate>{expirationDate}</ExpirationDate>
        <TransactionType>sale</TransactionType>
        <TransIndustryType>EC</TransIndustryType>
        <AcctType>R</AcctType>
        <HolderType>O</HolderType>
        <Amount>{amountInCents}</Amount>
        <CurrencyCode>USD</CurrencyCode>
    </requestMessage>
</requestHeader>

Every API response message from Beyond Pay contains a Token element. This Token represents the card number used in the original transaction, but is not considered a sensitive data element per the PCI DSS. To ease in identifying the original card, however, the last four digits of the Token are the same as the last four digits of the card number.

This Token value may be persisted and, with the cardholder's permission, associated with their user account in your application in order to make future purchases with the same card ("card-on-file").

Submitting a sale or sale-auth transaction with the Token as input requires use of the User and Password credentials in the request message, and also requires that the card ExpirationDate value be persisted and stored with the Token (the ExpirationDate value is returned in the original response message along with the Token).

Refunds and Voids

The GatewayTransId is returned in the response to a previous sale or sale-auth request and may be used as input to refund or void that original transaction.

<requestHeader>
    <ClientIdentifier>SOAP</ClientIdentifier>
    <TransactionID>{transactionId}</TransactionID>
    <RequestType>012</RequestType>
    <RequestDateTime>{requestDateTime}</RequestDateTime>
    <User>{Beyond-assigned username}</User>
    <Password>{Beyond-assigned password}</Password>
    <requestMessage>                    
        <SoftwareVendor>{yourSoftwareName}</SoftwareVendor>
        <TransactionType>refund</TransactionType>
        <ReferenceNumber>{original sale or sale-auth GatewayTransId}</ReferenceNumber>
        <Amount>{amountInCents}</Amount>
    </requestMessage>
</requestHeader>

In order to refund or void a previous sale or sale-auth transaction, simply construct an XML message with RequestType of 012 and TransactionType of refund. Note that if the original transaction is still in an unsettled batch, the gateway will perform a void/reversal transaction. If the original transaction has already settled, then the gateway will perform a refund to the original card.

Level II and Level III Data

Some business cards may be eligible for lower interchange rates if you send additional data with the transaction. Beyond Pay supports these additional data fields and can help you or your clients secure these significantly reduced rates and other B2B benefits.

Level II Data

Sample sale transaction with TokenPay.js and Level II data:

<requestHeader>
    <ClientIdentifier>SOAP</ClientIdentifier>
    <TransactionID>{transactionId}</TransactionID>
    <RequestType>004</RequestType>
    <RequestDateTime>{requestDateTime}</RequestDateTime>
    <PrivateKey>{yourPrivateKey}</PrivateKey>
    <AuthenticationTokenId>{token}</AuthenticationTokenId>
    <requestMessage>                    
        <SoftwareVendor>{yourSoftwareName}</SoftwareVendor>
        <TransIndustryType>EC</TransIndustryType>
        <TransactionType>sale</TransactionType>
        <AcctType>R</AcctType>
        <HolderType>O</HolderType>
        <Amount>{amountInCents}</Amount>
        <CurrencyCode>USD</CurrencyCode>
        <InvoiceNum>{yourInvoiceNumber}</InvoiceNum>
        <PONum>{yourPONumber}</PONum>
        <CustomerAccountCode>{customerCode}</CustomerAccountCode>
        <LocalTaxAmount>{taxAmount}</LocalTaxAmount>
        <LocalTaxIndicator>P</LocalTaxIndicator>
    </requestMessage>
</requestHeader>

In order for a transaction to qualify at reduced "Level II" interchange rates, assuming the card is eligible for such, the following fields should be provided in the XML message to the gateway in addition to the basic required fields given in the instructions for processing a basic sale transaction:

Level III Data

Sample sale transaction with TokenPay.js and Level III line-item details:

<requestHeader>
    <ClientIdentifier>SOAP</ClientIdentifier>
    <TransactionID>{transactionId}</TransactionID>
    <RequestType>004</RequestType>
    <RequestDateTime>{requestDateTime}</RequestDateTime>
    <PrivateKey>{yourPrivateKey}</PrivateKey>
    <AuthenticationTokenId>{token}</AuthenticationTokenId>
    <requestMessage>                    
        <SoftwareVendor>{yourSoftwareName}</SoftwareVendor>
        <TransIndustryType>EC</TransIndustryType>
        <TransactionType>sale</TransactionType>
        <AcctType>R</AcctType>
        <HolderType>O</HolderType>
        <Amount>{amountInCents}</Amount>
        <CurrencyCode>USD</CurrencyCode>
        <InvoiceNum>{yourInvoiceNumber}</InvoiceNum>
        <PONum>{yourPONumber}</PONum>
        <CustomerAccountCode>{customerCode}</CustomerAccountCode>
        <LocalTaxAmount>{taxAmount}</LocalTaxAmount>
        <LocalTaxIndicator>P</LocalTaxIndicator>
        <ItemCount>1</ItemCount>
        <Item>
          <ItemCode>{itemSKU}</ItemCode>
          <ItemCommodityCode>{UNSPSC code or merchantCategoryCode}</ItemCommodityCode>
          <ItemDescription>{shortDescriptionOfItem}</ItemDescription>
          <ItemQuantity>1</ItemQuantity>
          <ItemUnitCostAmt>{unitCostPerItem}</ItemUnitCostAmt>
          <ItemUnitMeasure>EA</ItemUnitMeasure>
          <ItemTotalAmount>{totalAmountForItem}</ItemTotalAmount>
        </Item>
    </requestMessage>
</requestHeader>

Cards that are eligible for Level III interchange rates are typically corporate purchasing or some travel cards. If a card is eligible for such, you can achieve a reduced interchange rate by providing the following fields in your gateway request message (in addition to those required for Level II and basic sale or "Level I" transactions).

Note that Level III transactions require line-item details from the purchase. You should send one Item array for each line item on a given invoice; many integrators will dynamically map these required fields into their existing inventory, order management, or ERP systems. Alternatively, if you only sell one type of item, you may consider creating a static mapping of these fields, or "hard-coding" the values specific to your business.

ACH and eChecks

<requestHeader>
    <ClientIdentifier>SOAP</ClientIdentifier>
    <TransactionID>{transactionId}</TransactionID>
    <RequestType>004</RequestType>
    <RequestDateTime>{requestDateTime}</RequestDateTime>
    <User>{Beyond-assigned username}</User>
    <Password>{Beyond-assigned password}</Password>
    <requestMessage>
        <SoftwareVendor>{yourSoftwareName}</SoftwareVendor>
        <TransactionType>sale</TransactionType>
        <TransIndustryType>{Standard Entry Class code; see below}</TransIndustryType>
        <RoutingNum>{bankRoutingNumber}</RoutingNum>
        <BankAccountNum>{bankAccountNumber}</BankAccountNum>
        <AcctType>{'S' for savings account; 'C' for checking account}</AcctType>
        <Amount>{amountInCents}</Amount>
    </requestMessage>
</requestHeader>

Processing an eCheck/ACH transaction is very similar to processing a credit card transaction. Instead of passing a token to the webservice, you can directly pass the bank's routing/transit number and the bank account number. These data elements are not considered sensitive to the same degree as card data, and are not covered by the scope of PCI DSS. You should still encrypt said data elements whether at rest or in motion, but they will not impact your scope of PCI compliance.

In addition to passing the routing and account number, you also need to specify whether the bank account is a checking or savings account, as well as the "Standard Entry Class" code as defined by NACHA.

In-Person Payments

Overview

If you are developing a payment application or point of sale (POS) system for use by only your business, then that application falls in your scope of PCI DSS compliance as a merchant. If you are developing a POS to sell or license to other businesses, that application is in scope for PCI Payment Application Data Security Standard (PA-DSS) if it interacts with card data. If that application is hosted/SaaS-based then you may also be in-scope PCI Service Provider (similar to a gateway provider).

The costs involved in validating PCI compliance for such software can be prohibitive for Indepdendent Software Vendors (ISVs). Increasingly, ISVs are also expected to offer support for EMV or chip cards: direct integration of which can also be very costly and time-consuming.

The solution to both of these challenges is a semi-integrated or "out-of-scope" architectural model, whereby a POS or application can integrate (or "semi-integrate") to a pre-certified payment application and device. This removes the burden of complicated EMV/chip card certification and insulates the application from interacting with sensitive data.

Beyond PayGuardian is a cloud-based semi-integrated solution that makes it possible to easily support in-person card payments from any platform or environment.

Supported Devices

Beyond's preferred card present devices are the Android-based "A-series" from PAX Technology:

Beyond also supports this semi-integration model using the Ingenico Telium2 family of devices, either through use of an additional network appliance or via OS-specific SDKs which are available by request.

Development devices are available to purchase by request. Please contact BeyondPayIntegrations@getbeyond.com.

Beyond will provide development and production devices pre-configured with the necessary account information and settings. The only credential you will need to communicate with the device is the UUID or "locationID", which will be provided by Beyond and can also be confirmed in the PayGuardian Cloud app on the the terminal device.

Getting Started

Sandbox Service (Testing):

https://pgc.bridgepaynetsecuretest.com/req/payment

Live Service (Production):

https://pgc.bridgepaynetsecuretx.com/req/payment

Credit Sale Request

POST

{
"locationID": "your-locationID",
"mode": "UAT",
"amount": "17.00",
"softwareVendor": "your_POS_name",
"tenderType": "CREDIT",
"transType": "SALE"
}

Credit Sale Response

{
"requestID": "2aaf2fe8663c561fe7edf5c663b4e7262dd47274bdba13f3daafb207",
"locationID": "91552FCB-01A7-4BA2-B00A-EA33FC660307",
"terminalID": "3EADDF76-27E6-4883-A49C-0AA876E64734",
"approvedAmount": "17.00",
"authCode": "830705",
"avsMessage": "",
"avsResponse": "",
"cardType": "Visa",
"cashBackAmt": "",
"cvMessage": "",
"cvResponse": "",
"expirationDate": "0323",
"extData": {
    "lodgingItem": [],
    "receiptTagData": {
        "maskedCard": "4***********2645",
        "chipCardAID": "A0000000031010",
        "invoice": "12345678",
        "seq": "23dbde68c492a6c2c6b5cbe726d40741",
        "authCode": "830705",
        "entryMethod": "Chip_Read",
        "totalAmount": "17.00",
        "pinVerified": "NO"
    },
    "signatureEncoded": "iVBORw0KGgoAAAANSUhEUgAAAe8AAACWCAIAAAB4sZcnAAADOklEQVR42u..."
},
"gatewayMessage": "A01 - Approved",
"gatewayResult": "0",
"internalMessage": "Approved: 830705 (approval code)",
"isCommercialCard": "False",
"isoCountryCode": "840",
"isoCurrencyCode": "USD",
"isoRequestDate": "2018-06-28 14:25:04.963",
"isoTransactionDate": "2018-06-28 14:25:04.963",
"maskedAccountNumber": "4***********2645",
"merchantCategoryCode": "",
"networkMerchantId": "",
"networkReferenceNumber": "",
"networkTerminalId": "",
"pnRefNum": "253271004",
"remainingAmount": "0.00",
"requestedAmount": "",
"responseTypeDescription": "sale",
"resultCode": "0",
"resultTxt": "Successful Request",
"streetMatchMessage": "",
"submittedAmount": "17.00",
"timestamp": "20180628",
"tipAmount": "",
"token": "11110000000400142645",
"transactionCode": "23dbde68c492a6c2c6b5cbe726d40741"
}

Initiating a card present transaction is as simple as POSTing just a few lines of JSON to the webservice, passing the following arguments:

If the card is an EMV/chip card, then the user will be presented with an option to select whichever Applications reside on the chip (that is, they can select an Application ID associated with either Credit or Debit, depending on their card) regardless of what tender type is sent in the request. This is the primary usage of the UNKNOWN tender type as well.

If the card is magnetic stripe only and capable of being processed as either a debit or a credit transaction, then it will be processed as whatever tender type is sent in the request. If UNKNOWN is selected, the cardholder will likewise be prompted to make the selection.

Transaction types may be defined as follows:

Basic Sale Options

{
"locationID": "your-locationID",
"mode": "UAT",
"amount": "#####.##",
"softwareVendor": "your_POS_name",
"tenderType": "CREDIT",
"transType": "SALE",
"invNum": "Invoice number",
"pnRefNum": "Reference number from a previous transaction",
"poNum": "Purchase order number",
"taxAmt": "#####.##",
"allowPartialApproval": "true|false",
"clerkID": "Employee/Clerk ID",
}

You may also want to send these additional fields on some transactions:

Tips & Gratuities

CREDIT+ADJUSTMENT request:

{
"locationID": "C832D913-982C-4256-9895-2DD13BDA5947",
"pnRefNum": "Reference number from a previous transaction",
"mode":"UAT",
"tipAmt": "5.00",
"tenderType": "CREDIT",
"transType": "ADJUSTMENT"
}

CREDIT+ADJUSTMENT response:

{
"requestID": "388c37acbd88d7f00fce90ffee8b83c156efedb57828c1e8439e6284",
"locationID": "C832D913-982C-4256-9895-2DD13BDA5947",
"terminalID": "9102C064-F990-41AB-BAD4-C98F33E4C684",
"approvedAmount": "20.00",
"authCode": "802431",
"avsMessage": "",
"avsResponse": "",
"cardType": "",
"cashBackAmt": "",
"cvMessage": "",
"cvResponse": "",
"expirationDate": "",
"extData": {
    "lodgingItem": [],
    "receiptTagData": {}
            }   , "gatewayMessage": "A12 - Tip Adjustment Posted",
"gatewayResult": "0",
"internalMessage": "Tip Adjustment Posted",
"isCommercialCard": "False",
"isoCountryCode": "0",
"isoCurrencyCode": "",
"isoRequestDate": "",
"isoTransactionDate": "",
"maskedAccountNumber": "",
"merchantCategoryCode": "",
"networkMerchantId": "",
"networkReferenceNumber": "",
"networkTerminalId": "",
"pnRefNum": "253276004",
"remainingAmount": "0.00",
"requestedAmount": "",
"resultCode": "0",
"resultTxt": "Successful Request",
"streetMatchMessage": "",
"submittedAmount": "15.00",
"timestamp": "",
"tipAmount": "",
"token": "",
"transactionCode": ""
}

tenderType=CREDIT and transType=ADJUSTMENT will adjust a previous SALE or SALE_AUTH adding a tip amount based on a pnRefNum. This can only be performed on unsettled transactions in an open batch. If successful, the response will contain the new total approved amount: (initial amount) + (tip amount).

Lodging & Hotels

{
"locationID": "your-locationID",
"mode": "UAT",
"amount": "10.00",
"softwareVendor": "your_POS_name",
"tenderType": "CREDIT",
"transType": "SALE",
"extData": {
/* Lodging fields */
"checkInDate": "Actual or anticipated check in date.",
"checkOutDate": "Actual or anticipated check out date.",
"departureAdjAmount": "Additional amount charged after cardholder left the hotel.",
"folioNumber": "Hotel folio number",
"lodgingChargeType": "H (Hotel)|R (Restaurant)|G (Gift Shop)|S (Health Spa)|B (Beauty Shop)|F (Convention Fee)|T (Tennis)|O (Golf)",
/*Collection of lodging item records.*/
"lodgingItem": [{
"lodgingItemAmount": "Amount (in cents) for lodging extra charge item. Implied (no) decimal.",
"lodgingItemCode": "",
"lodgingItemType": "G (Gift Shop)|L (Laundry)|B (Mini Bar)|R (Restaurant)|T (Telephone)"
}],
"lodgingItemCount": "Indicates number of lodging industry items purchased as part of this transaction.",
"roomNumber": "Hotel room number",
"roomRateAmt": "Amount (in cents) of the daily room rate.",
"roomTaxAmt": "Amount (in cents) of the tax applied to daily room rate.",
"specialProgramType": "AD (Advance deposit)|AR (Assured reservation)|DC (Delayed charge)|ES (Express service)|NC (Normal charge)|NS (No show charge)",
"stayDuration": "Anticipated, actual or incremental stay in days."
}

The extended data fields required for lodging transactions can easily be passed through the semi-integrated device to Beyond Pay Gateway.

Pharmacy & Healthcare

{
"locationID": "your-locationID",
"mode": "UAT",
"amount": "10.00",
"softwareVendor": "your_POS_name",
"tenderType": "CREDIT",
"transType": "SALE",
/* Healthcare related fields */
"isQualifiedIIAS": "Indicates whether purchase items are verified against IIAS. Can be t|f",
"healthCareAmt": "Amount (in cents) of the total Healthcare Amount.",
"clinicAmt": "Amount (in cents) of the portion of the Healthcare Amount spent on hospitalization.",
"dentalAmt": "Amount (in cents) of the portion of the Healthcare Amount spent on dental related medical services.",
"prescriptionAmt": "Amount (in cents) of the portion of the Healthcare Amount spent on prescription drugs or products.",
"transitAmt": "Amount (in cents) of the portion of the Healthcare Amount spent on transportaion.",
"visionAmt": "Amount (in cents) of the portion of the Healthcare Amount spent on vision related medical services."
}

Payment systems and Points of Sale for pharmacy merchants are required to pass some of these additional data fields in conjunction with their implementation of "auto-substantiation" using an "inventory information approval system" (IIAS). See sig-is.org for more information.

Transaction Reporting

Reporting SDK (C#)

Web Service: https://api.getbeyondpay.com/Reporting.API/ReportingAPI.svc

C# sample implementation:

class Program
{
  static void Main(string[] args)
  {
    ReportingAPI.Credentials credentials = new ReportingAPI.Credentials();

    credentials.UserName = "username";
    credentials.Password = "password";

    ReportingAPI.ReportingAPIV1Client client = new ReportingAPI.ReportingAPIV1Client();
    ReportingAPI.TransactionRowFilter filter = new ReportingAPI.TransactionRowFilter();

    filter.MerchantID = 2000;
    filter.MerchantAccountID = 2001;

    filter.DateRangeFrom = DateTime.Now.AddMonths(-2);
    filter.DateRangeTo = DateTime.Now;

    filter.Skip = 0;
    filter.Take = 20;

    ReportingAPI.TransactionSet ts = new ReportingAPI.TransactionSet();

    Ts = client.PublicGetTransactionsByFilter(credentials, filter);

    foreach (ReportingAPI.TransactionRow tr in ts.TransactionList)
    {
      Console.WriteLine("Transaction ID: " + tr.TransactionId); 
      Console.WriteLine("Sale Date / Time: " + tr.SaleDateTime); 
      Console.WriteLine("Merchant Name: " + tr.MerchantName); 
      Console.WriteLine("Card Holder Name: " + tr.FirstName + " " + tr.LastName); 
      Console.WriteLine("Invoice Number: " + tr.InvoiceNumber); 
      Console.WriteLine("Auth Code: " + tr.AuthCode); 
      Console.WriteLine("Requested Amount: " + tr.RequestedAmount); 
      Console.WriteLine("Authorized Amount: " + tr.AuthorizedAmount); 
      Console.WriteLine("Remaining Amount: " + tr.RemainingAmount); 
      Console.WriteLine("Settle Anmount: " + tr.SettleAmnount); 
      Console.WriteLine("--------------------------------------------");
    }
  }
}

The Beyond Pay Reporting API provides integrators with the ability to request transaction data via a SOAP request made to the service. The user must provide data they wish to use as a filter in the parameter to the SOAP method and will receive a response containing the data they requested.

The Reporting API provides three data contracts. One for the incoming request and two for the response to the request. When making a request, the consumer must provide a TransctionRowFilter object. When receiving the response, the consumer will get a TransactionSet object which will contain a collection of TransactionRow objects. The data contracts are described in more detail below.

TransactionRowFilter

Parameter Name Data Type Validations Comparison Type
AmountRangeFrom Implied Integer Optional GTE
AmountRangeTo Implied Integer Optional
AuthorizationCode String Optional, Exact Match EQUIV
BatchID Integer Optional EQUIV
CardBrand String Optional, Must match known card brands EQUIV
CardholderFirstName String Optional, Exact Match EQUIV
CardholderLastName String Optional, Partial Match CONTAINS
ClerkId String Optional, Exact Match EQUIV
CustomerNumber String Optional, Exact Match EQUIV
DateRangeFrom DateTime Optional GTE
DateRangeTo DateTime Optional LTE
EndPartialAccountNumber String Optional EQUIV
ExcludeTransResults* Boolean Optional (1 or 0) N/A
ExcludeVoid Boolean Optional (1 or 0) N/A
ID Integer Optional, Exact Match EQUIV
InvoiceNumber String Optional, Exact Match EQUIV
MerchantAccountId Integer Optional EQUIV
MerchantId Integer Optional EQUIV
PaymentMethodID String Optional, Exact Match EQUIV
PurchaseOrderNumber String Optional, Exact Match EQUIV
ResellerID Integer Optional EQUIV
ResponseCode String Optional, Partial Match CONTAINS
SettlementStatus String Optional, Exact Match EQUIV
Skip Integer Required N/A
Take Integer Required N/A
TransactionSourceIP String Optional, Exact Match EQUIV
TransactionStatus String Optional, Exact Match EQUIV
TransResults* String Optional, Multi-Match (comma separated list) INLIST

The TransResults field works by mapping theb 5-digit Beyond Pay Gateway Result code back to the gateway response code (the ResponseCode or Gateway Message code field in this contract). In some cases, more than one mapping may exist for a given code. It is recommended that you use the ResponseCode or Gateway Message code field for more granular filtering. The ExcludeTransResults field can modify the behavior of the TransResults field by establishing a "not in" condition.

TransactionSet

Parameter Name Data Type Description
RecordCount Integer The total number of records that match the filter, excluding the Take & Skip fields.
TransactionList List A collection of TransactionRow objects.

TransactionRow

Parameter Name Data Type Description
Account Type String 1 character identifier that determines the type of account. Valid values are R (Branded Credit Card), E (Branded debit checking card), V (Branded debit savings card), D (Unbranded debit checking card), I (Unbranded debit savings card), S (Bank savings account), C (Bank checking account), F (EBT food stamp), H (EBT cash benefit), G (Gift card), L (Fleet), A (Cash), K (Check)
AuthCode String The Authorization Code provided by the card issuer
AuthorizedAmount Implied Integer The amount that was actually authorized. This may be different from the requested amount (e.g., partial approvals)
BatchDateTime DateTime The close date of the batch that contains the transaction
BatchId Integer The gateway Batch ID that contains this transaction
CardBrand String Description of the card brand used. Valid values: AMEX, DISCOVER, MASTERCARD, DINERS, and VISA
ClerkId String The client-supplied Clerk ID (or the Username used to process the transaction if no Clerk ID was provided)
ClerkName String The client-supplied name of the Clerk who processed the transaction
CustomerAddress String The client-provided Street Address for the transaction
CustomerEmail String The client-provided Email Address for the transaction
CustomerNumber String The client-provided Customer ID
CustomerZip String The client-provided Zip Code
EntryModeId String Identifies how the transaction was processed. Valid valus are T1 (Track 1 Data), T2 (Track 2 Data), T3 (Track 1 and 2 Data), KD (Keyed)
ExpirationDate String Month and Year of the card expiry date in MMYY format
FirstName String First name of the account holder
HolderType String A one-character code identifying if the payment method was a personal account (P) or a business/corporate account (O)
InvoiceNumber String The client-provided Invoice Number
LastFour String The last four digits of the Primary Account Number (card number)
LastName String The last name of the account holder
MaskedAccount String A masked version of the account number used to process the transaction
Memo String The client-provided "PaymentType" value
MerchantAccountId Integer The "MerchantAccountCode" for the transaction
MerchantAccount Integer The "MerchantAccount" for the transaction
PaymentMethodId String Two letter code that identifies the payment method transaction type. Valid values: AC (Amex), BC (Bank Checking), BD (Bank Card Debit), BS (Bank Savings), DC (Discover Credit), DD (Discover Debit), EC (EBT Cash Benefit), EF (Food Stamps), FL (Fleet One), GF (Fuelman Fleet Wide), GG (General Gift), MC (Master Card Credit), MD (Master Card Debit), MF (Master Card Fleet), MP (Master Card Prepaid), NC (Diner’s Club), VC (Visa Credit), VD (Visa Debit), VF (Voyager), VP (Visa Prepaid), VS (Visa Fleet), WX (Wright Express)
ProcessorResponse String Description of the response provided by the account issuer
PurchaseOrderNumber String The client-provided Purchase Order Number
RemainingAmount Implied Integer The amount of the authorization that is remaining after partial refunds or voids have been applied
RequestedAmount Implied Integer The amount that was requested to be authorized when the transaction was processed
ResellerId Integer The gateway reseller ID for the transaction
ResponseCode String The 3-character Gateway Message code
SaleDateTime DateTime The date and time the transaction was processed
SettleAmount Implied Integer The amount of the transaction that was actually settled. This may be different than the requested or authorized amounts.
SettlementStatus String Identifies whether the transaction has been settled yet or not. Valid valuies: Settled, Unsettled
TerminalId String Reserved for Future Use
Token String The tokenized account number
TransactionId Long Integer The unique gateway ID for the transaction
TransactionIndustryType String A 2-3 character string that identifies what industry or SEC code the transaction was processed under. Valid values: RE (Retail), DM (Direct Marketing), EC (eCommerce), RS (Restaurant), LD (Lodging), PT (Petroleum), POP (Point Of Purchase), PPD (Prearranged Payment and Deposit), CCD (Corporate Credit or Debit), TEL (Telephone Initiated Entry), WEB (Internet Initiated Entry), C21 (Check 21)
TransactionSourceIP String The IP Address and Port where the transaction request originated
TransactionStatus String Identifies what state the transaction is in. Valid values: Open, Confirmed, or Voided.
TransactionType String Identifies the type of transaction that was requested. Valid values: Sale, Sale-Auth (authorization only), Credit, Void, Refund, Increment (incremental authorization).
VoidIndicator Boolean Indicates whether or not the transaction was voided before the batch was settled

Operation Contract

This method returns a TransactionSet object as described above:

PublicGetTransactionsByFilter(Credentials credentials, TransactionRowFilter filterObject)

At this time, the Reporting API provides only one operation contract for retrieving transactional data.

Reporting Tips and Examples

There are two types of parameters in the TransactionRowFilter object: DBQuery Filters and Post-Query Filters.

Most of the parameters in the filter are DBQuery filters that are used directly against the persisted data store that contains the transactional data. However, some of the filters are Post-Query filters, meaning the filters are not applied until after the persisted data is retrieved. Post-Query filters have transformational logic that is better suited after the bulk of the query has been processed by the data store.

Filters that are processed directly against the data store also have specific comparison modes that can be utilized for easier queries. Review the comparison modes listed in the TransactionRowFilter table for a full list.

Examples:

Returns all transactions of $1.00 or more:

<AmountRangeFrom>100</AmountRangeFrom>

Returns all transactions of $2.00 or less:

<AmountRangeTo>200</AmountRangeTo>

Returns all transactions with Invoice Number 2001:

<InoviceNumber>2001</InvoiceNumber>

Returns all declined transactions:

<ResponseCode>D</ResponseCode>

Returns all declined transactions with Gateway Message codes D01–D09:

<ResponseCode>D0</ResponseCode>

Returns only those transactions that were declined with Gateway Message code D01:

<ResponseCode>D01</ResponseCode>

Provides those transactions where the Gateway Result code is equal to 00000, 00001, or 10012 only

<TransResults>00000,00001,10012</TransResults>

Return all transactions where the Gateway Result code is NOT equal to 00000, 00001, or 10012:

<TransResults>00000,00001,10012</TransResults>
<ExcludeTransResults>1</ExcludeTransResults>

Comparison Types

NOTE: ExcludeTransResults must be used with TransResults. It modifies the behavior of the TransResults field.

Post-Query Filters

The following fields are Post-Query filters. They will not process until after the initial data store query has completed.

The data used to query on these parameters must be transformed before the filter can be applied. The data store resources are too time-consuming for these filters and they are therefore added after the data store query is completed. You should never use a Post-Query Filter without first limiting the data store query with some DBQuery filters such as a date range and/or the merchant account information.

Response Codes

AVS Response Codes

Response Code Description
00 AVS Error - Retry, System unavailable or Timed out
40 Address not available (Address not verified)
43 Street address not available (not verified), ZIP matches
44 Address failed
45 Street address and ZIP don't match
46 Street address doesn't match, 5-digit ZIP matches
47 Street address doesn't match, 9-digit ZIP matches
4A Street address or ZIP doesn't match
4D Street address matches, ZIP does not
4E Street address and 5-digit ZIP match
4F Street address and ZIP match
53 Account holder name incorrect, billing postal code matches
55 Unrecognized response
5C Account holder name incorrect, billing address matches
5F Account holder name incorrect, billing address and postal code match
70 Account holder name matches
73 Account holder name and billing postal code match
7C Account holder name and billing address match
7F Account holder name, billing address and postal code match
80 AVS service not supported by issuer - Issuer doesn't participate in AVS

CVV Response Codes

Response Code Description
M Matches
N No match
P Not processed
S Should be present
U Issuer is not certified
X Unrecognized reason

Gateway Message Codes

Gateway Message Code Message
A01 Approved: XXXXXX (approval code)
A02 Credit Posted
A03 Void Posted (Auth Reversed)
A04 No Update
A05 Partially Approved
A06 Void Posted (Auth Not Reversed)
A07 Partial Void Posted
A08 Partial Refund Posted
A09 Incremental Auth Posted
A10 Request Accepted
A11 Approval (Reversal failed)
A60 Terminal Offline Approval - EMV/Chip
A61 Terminal Offline Approval - Swipe
A62 Terminal Offline Approval - Credit
D01 Denied by customer's bank
D02 Invalid Expiration Date
D03 Insufficient funds
D04 Hold - Pick up card
D05 Invalid card number
D06 No account
D07 Incorrect PIN
D08 CSC is invalid
D09 Duplicate Transaction
D10 Card reported lost/stolen
D11 Card reported stolen
D12 Service not allowed
D13 Stop Recurring
D15 Maximum transaction limit is exceeded
D16 Card is expired
D17 Re-enter Transaction
D18 Bad Amount
D19 Unmapped decline
D20 Billing profile configuration error
D21 PIN try excdeed
D22 Refund was not processed/received
D24 Chargeback received
D25 Refund limit is reached for the day
D26 Settlement Failed
D27 Transaction Error
D28 Cashback limit exceeded/Cashback unavailable
D29 Card is restricted
D30 Call for Authorization
D31 Declined due to fraud rules
D32 Declined due to fraud engine decision
D33 Incorrect merchant setup
D34 Merchant profile configuration issue
D35 Card chip decline
E02 Processing Network Unavailable
E03 Transaction data integrity validation error
E04 Refund limit is reached for the day
E06 Card is blacklisted
E07 Tokenization is not supported
E08 Refunds are not allowed
E09 Processing Network Error
E10 3D Secure Verification Failed
E31 Declined due to pre-processing rules
X01 Processing Cancelled by User
X02 Pending processing
X03 3D Secure Verification Required
X04 Processing cancelled: the request has expired

Gateway Result Codes

Result Code Description
000 Successful request
00001 Partial Authorization
10001 Missing Reference Number
10002 Invalid Card Number - Blank/Null
10003 Invalid Card Type - Doesn't match accepted card types
10004 Invalid Expiration Date - Blank/Null
10005 Invalid Security Code - Blank/Null
10007 Invalid Card Number - Not Numeric
10008 Invalid Length for card type
10009 Invalid Expiration Date - Card Expired
10010 Invalid Security Code - Not Numeric
10011 Invalid Transaction ID
10012 Invalid Card Number - Failed Mod10
10013 Invalid Expiration Date Value
10014 Invalid Security Code Length
10017 Invalid Expiration Date - Invalid Month
10018 Invalid Expiration Date - Invalid Year
10019 Invalid Expiration Date
10020 Invalid Client Identifier
10021 Invalid Request Element – Missing Element
10022 Invalid Request Type
10023 Password Expired
10024 Invalid Credentials
10025 Invalid Zip – Not Numeric
10026 Invalid Zip – Wrong Length
10027 Invalid Amount – Blank/Null
10028 Invalid Amount – Not Numeric
10029 Invalid Request Date/Time
10030 Invalid Token
10031 Invalid Track
10032 Invalid Track Identifier
10033 Invalid Void Request
10034 Invalid Encryption ID
10035 Invalid Account Number – Blank/Null
10036 Invalid Account Number – Not Numeric
10037 Invalid Payment Type – Blank/Null
10038 Invalid Payment Type – Unrecognized Payment Type
10039 Invalid Account Number – Account Number Does Not Exist
10040 Missing Required Pass-Thru Data Element
10041 Missing / Invalid BIN
10042 Already Voided
10050 Incorrect Trace Number
10051 Incorrect Merchant Setup
10052 Processing Network Error
10053 Credit Card Entry Refused by Receiver
10054 Mandatory Field Error
20001 Tokenization Service Connection Error
20002 Beyond Pay Internal Server Error
20003 Client Service Unavailable
20004 Payment Service Sensitive Data Timeout
30004 Invalid Request Message
30005 Invalid Response Message
30006 New Password Doesn't Match Confirmation Password
30007 New Password Too Weak
30008 Missing Payment Card Data
30009 Internal Payment Card Data Error
30010 Invalid Record Format
30011 Invalid Merchant Number (from Gateway)
30012 Bad Card Number (from Gateway)
30013 Invalid Store Number
30020 Invalid Transaction Industry Type
30021 Missing Transaction Industry Type
30022 Processing Network Unavailable
30023 Invalid Account Number
30024 No Account
30025 Invalid Security Code
30026 Invalid Amount
30027 Refund limit is reached for the day (occurs when merchant has reached the refund limit allowed per day on the account)
30028 Settlement Failed
30029 Transaction Error
30030 Transaction data integrity validation error
30032 Denied by customer’s bank
30033 Insufficient funds
30034 Hold - Pick up card
30035 Incorrect PIN
30036 Duplicate Transaction
30037 Card reported lost
30038 Card reported stolen
30039 Service not allowed
30040 Stop Recurring
30041 Unattempted Batch Decline
30042 Maximum transaction limit is exceeded at the moment. Try processing your transaction tomorrow.
30043 Re-enter Transaction
30044 Unmapped decline
30045 Billing profile configuration error
30046 Pin Try Exceeded
30047 Refund was not processed/received
30048 Chargeback received
30049 Processing Canceled by User
30050 Invalid Transaction Category
30051 Invalid Verification Status
30052 Invalid Terminal Type
30053 Invalid Petroleum Product Type
30060 Invalid IApp User Id
30061 Account insert failed
30062 Merchant insert failed
30070 New Password Previously Used
30071 Missing Clerk Id
30072 Call for Authorization
30073 Card is Restricted
30074 Declined due to fraud rules
30075 Bank Account Blacklisted
30076 Declined due to insufficient information
30077 Rejected by the processor
30078 Account Closed
30079 Invalid Account
30080 Account can not process ACH
30082 Invalid MICR
30083 Customer opt out check Conversion
30100 Invalid Account Data – Blank/Null
30101 Invalid EMV Tag Data – Blank/Null
40001 Lodging Reauth Failed
40002 Missing Lodging Folio Number
80000 Gateway Services Available
80001 Gateway Services Unavailable
80002 Invalid Purchase Token
80003 More than one result found for search criteria
80004 More than one service fee block received in request message
80005 Cascade Void. Indicates that the transaction was successfully authorized (fully or partially) and then voided due to an auto-void policy setting. Only occurs on principal transactions and only when the accompanying service fee was either declined or voided due to an auto-void policy setting.
80006 Partial Auto Void. Indicates that the transaction was partially authorized and then voided due to an auto-void policy setting. Can occur on a service fee or principal transaction.
80007 Database query processing error. Can occur on a Find Transaction request if the data requested is unavailable.
80008 Invalid GatewayTransID
80009 Invalid MerchantCode
800010 Invalid MerchantAccountCode
800011 Transaction not found
800012 Invalid Length for PersistData
90000 Token Store failed to encrypt a token
90001 Token Store failed to decrypt a token
99999 Unknown Error

PayGuardian Response Codes

Response Code Description
0 Approved
1 Declined
2 Error
12 EMV Chip Declined

Testing & Certification

Certification

When you are finished developing your interface to one of the Beyond Pay solutions, please contact us to get certified and obtain your production keys!

Test Cards and Checks

You can use the following card numbers for testing. CVV numbers are 1234 or 1111 for Amex; all others are 111 or 999.

Card Type Card Brand Card Number Expiration Date
Credit Visa 4111111111111111 10/25
Credit MasterCard 5499740000000057 10/25
Credit Discover 6011000991001201 10/25
Credit Amex 371449635392376 10/25
Debit Visa 4217651111111119 10/25
Debit MasterCard 5149612222222229 10/25

The following information may be used for ACH / eCheck testing:

Bank Account Number Routing Number Account Type
4099999992 021000021 Checking

Trigger Amounts

As part of your development and testing efforts, the amount ranges specified below can be used to trigger specific response codes from the server. These test ranges may be used with any valid card number.

Card Response Triggers

Amount Response Code Response Message
0.01 - 0.99 D01 Denied by customer's bank (Do Not Honor)
1.00 A01 Approved
1.01 - 4.98 D01 Denied by customer's bank (Do Not Honor)
4.99 20002 Internal ServerError
5.00 - 69.99 A01 Approved
70.00 - 79.99 D05 Invalid card number
80.00 - 89.99 D10 Card reported lost/stolen
90.00 - 99.99 D30 Call for authorization
100.00 - 109.99 D04 Pick up card
110.00 - 119.99 D08 Invalid security code
120.00 - 129.99 D03 Insufficient funds
130.00 - 139.99 E02 Processing network unavailable
140.00 - 149.99 E09 Internal ServerError
150.00 - 159.99 A05 Partially approved [approved amount will be $10 less than the requested amount]
170.00 - 181.99 A01 Approved
182.00 - 1999.99 D01 Denied by customer's bank (Do Not Honor)

ACH/eCheck Response Triggers

Amount Response Code Response Message
170.00 - 171.99 C01 Customer's account number is incorrect
172.00 - 173.99 C02 Customer's routing number is incorrect
174.00 - 175.99 C03 Customer's routing number and DFI account numbers are incorrect
176.00 - 177.99 C04 Customer's name is incorrect
178.00 - 179.00 C05 Customer's account type (Savings/Checking) is incorrect
180.00 - 181.99 C06 Account number is incorrect and transaction is being routed to the wrong type of account

AVS Response Triggers

ZIP Code AVS Response Code AVS Response Message
11111 00 AVS Error - Retry, System unavailable, or Timed out
22222 46 Street address doesn't match, 5-digit ZIP matches
33333 43 Street address not available (not verified), ZIP matches
44444 40 Address failed
55555 4F Street address and ZIP match

Refund ("Blind Credit") Response Triggers

Amount Response Code Response Message
0.01 - 4.99 D01 Denied by customer's bank (Do Not Honor)
5.00 - 69.99 A02 Credit Posted
70.00+ D01 Denied by customer's bank (Do Not Honor)