NAV Navbar

Beyond Pay Gateway

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

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 maximizes the user experience by allowing for the capture of sensitive card data within the payment form of the merchant’s website or mobile application. The consumer remains on the merchant’s payment page at all times during the checkout process.

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, 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 token. If there are any errors in the collection of the card data or creation of the 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.

Submit a Sale using 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 charge the card or save the token for future use. Charges against cards that are tokenized in the browser using TokenPay.js must ONLY made from your server.

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

Now submit the token and parameters according to the Beyond Pay Gateway API Guide, with the following substitutions:

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

Perform an "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.

Tokenization and Repeat Sales from 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 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.

In-Person Payments

PayGuardian

CERTIFIED DEVICES

Point‐of‐Sale (POS) systems that process sensitive payment information are required to certify their payment applications to the Payment Application Data Security Standard (PA‐DSS). The addition of EMV certification and continued need for both encryption and tokenization has become a concern for both merchants and integrators. Instituting and maintaining these standards requires significant financial and employee resources in order to adhere to the Payments Card Industry Data Security Standards (PCI DSS) compliance requirements. Subsequently, any changes made in the POS system, may require a partial or full recertification, which increases the cost and time to market. Beyond has engaged these issues through our product line, the PayGuardian suite, to better serve the needs of our integrators and merchants.

PayGuardian is a lightweight, highly secure client application that integrates seamlessly into POS applications. PayGuardian facilitates the transaction process by handling the collection and transmission of sensitive payment information as an out of scope PA-DSS solution, thereby offloading the certification responsibility from merchants and integrators. PayGuardian is EMV enabled, handles point to point encryption, and tokenizes all transactions to ensure transaction processing is seamless and secure.

PayGuardian Desktop

Download PayGuardian Desktop v 2.4.4

PayGuardian Desktop Developer Guide

PayGuardian Desktop Installation Guide

PayGuardian Desktop User Guide

Sample C# DLL integration:

private void ProcessCreditCard_Click(object sender, EventArgs e)
  {
    // 1. First create a Payment Page
    hostName=hostname.Text;
    PaymentPage pg=newPaymentPage();
    PaymentRequest paymentRequest=pg.PaymentRequest;
    paymentRequest.TenderType=PaymentRequest.ParseTenderType(TenderType.Text);
    paymentRequest.TransType=PaymentRequest.ParseTransType(TransType.Text);

    // 2. Next, set the PayLink Properties
    #regionSetPayLinkProperties

    // Set the only required field (Amount)
    paymentRequest.Amount = this.Amount.Text.ToString();

    // 3. Display the payment processing page
    ShowPageResult result = null;
    try
    {
      Result = pg.ShowPage();
    }
    catch (Exception)
    {
      // Error while processing payment
      MessageBox.Show("Error Processing Payment");
    }
    PaymentResponse paymentResponse = pg.PaymentResponse;

    // 4. Display the result of the transaction
    #region Show the PayLink Result

    If (result != null && result.code == ShowPageResultCode.OK)

   //TO DO - finish

PayGuardian Desktop (for Windows) comes with an executable installer file that integrators may incorporate into their Point-of-Sale system installation. A Windows object library has also been included to enable easy integrations with POS applications. The object library is accessible using Component Object Model (COM) or .NET technology.When invoked, PayGuardian displays a basic frame that encapsulates the browser, fetching and rendering the Virtual Terminal (VT)page. The object window is configurable, and integrators can brand the user interface using cascading style sheets. The VT object window holds focus, floating on top of all other running applications.

PayGuardian iOS SDK

iOS Framework

iOS Developer Guide

Test iOS App

Create a BPNPaymentRequest object:

-(instancetype) initInvoiceNumber:(NSString *_Nonnull) invoiceNumber
pnRefNum:(NSString *_Nullable) pnRefNum 
amount:(NSDecimalNumber *_Nullable) amount 
tipAmount:(NSDecimalNumber *_Nullable) tipAmount 
cashBackAmount:(NSDecimalNumber *_Nullable) cashBackAmount 
tenderType:(NSString *_Nonnull) tenderType 
transactionType:(NSString *_Nonnull) transactionType 
username:(NSString *_Nonnull) username 
password:(NSString *_Nonnull) password 
merchantCode:(NSString *_Nonnull) merchantCode 
merchantAccountCode:(NSString *_Nonnull) merchantAccountCode 
paymentAccountNumber:(NSString *_Nullable) paymentAccountNumber 
token:(NSString *_Nullable) token 
expirationDate:(NSString *_Nullable) expirationDate 
terminalCommConfig:(TerminalCommConfig *_Nonnull) terminalCommConfig
industryType:(NSString *_Nonnull) industryType 
healthCareData:(BPNHealthCare *_Nullable) healthCareData 
bankAccountNumber:(NSString *_Nullable) bankAccountNumber
routingNumber:(NSString *_Nullable) routingNumber
partialApproval:(BOOL) partialApproval
enableTpi:(BOOL) enableTpi
signatureData:(NSString *_Nullable) signatureData
disableAmountConfirmation:(BOOL) disableAmountConfirmation
testMode:(BOOL) testMode;

Construct the PayGuardianTransaction object:

initWithPaymentRequest:(BPNPaymentRequest *)request;

The run method with completion is:

-(void)runOnCompletion:(void (^)(BPNPayment *payment, NSError *error)) onCompletion onStateChanged:(void (^)(PayGuardianTransactionState state)) onStateChanged;

Implement a handler for the returned BPNPayment response:

BPNPayment.BridgeCommResponse:
transactionID: 8888
requestType: 004
responseCode: 0
responseDescription: Successful Request
token: 11110000000068530608
expirationDate: 1225
authorizationCode: 290144
originalReferenceNumber: MCC7754741020
authorizedAmount: $5.50
originalAmount: $5.50
gatewayTransactionID: 214973401
gatewayMessage: A01 -Approved
internalMessage: Approved: 290144 (approval code)
gatewayResult: 00000
AVSMessage:
AVSResponse:
CVMessage:
CVResult:
transactionCode: (null)
transactionDate: 20161020
remainingAmount: $0.00
ISOCountryCode: (null)
ISOCurrencyCode: USD
ISOTransactionDate: 2016-10-20 14:32:47.86
ISORequestDate: 2016-10-20 14:32:47.86
networkReferenceNumber: MCC7754741020
merchantCategoryCode:
networkMerchantID: 518564010126944
networkTerminalID: PPB01.
cardType: Mastercard
maskedPAN: 5***********0608
responseTypeDescription: sale
isCommercialCard: False
streetMatchMessage:
secondsRemaining: (null)
merchantCode: (null)
merchantAccountCode: (null)
merchantName: (null)
receiptTagData: (null)
issuerTagData: (null)
applicationIdentifier: (null)
terminalVerificationResults: (null)
issuerApplicationData: (null)
transactionStatusInformation: (null)

PayGuardian iOS is a secure iOS framework library that integrates seamlessly into iOS applications. PayGuardian iOS facilitates the transaction process by handling the collection and transmission of sensitive payment information as an out of scope PA-DSS solution, thereby offloading the certification responsibility from merchants and integrators. PayGuardian iOS is EMV enabled, handles point to point encryption, and tokenizes all transactions to ensure transaction processing is seamless and secure.

Programmatically, a PayGuardian iOS transaction is comprised of a four step process:

PayGuardian Android SDK

PayGuardian for Android

Android Developer Guide

Android app-to-app sample project

Java sample (App-to-App method):

public void processTransaction(String paymentRequestXml)
  {
    final int PAYGUARDIAN_REQUEST_CODE = 102;
    Intent sendIntent = new Intent(android.content.Intent.ACTION_SEND);
    sendIntent.setType("text/plain");
    sendIntent.putExtra(Intent.EXTRA_TEXT, paymentInputXml);

    PackageManager pm = getApplicationContext().getPackageManager();
    List<ResolveInfo> activityList = pm.queryIntentActivities(sendIntent, 0);

    for (final ResolveInfo app : activityList)
    {
      if ((app.activityInfo.name).contains("ProcessSecurelyActivity"))
      {
        final ActivityInfo activity = app.activityInfo;
        final ComponentName name = new ComponentName(activity.applicationInfo.packageName, activity.name);

        sendIntent.setComponent(name);

        startActivityForResult(sendIntent, PAYGUARDIAN_REQUEST_CODE);

        break;
      }
    }

PayGuardian Android is a lightweight, highly secure Android application that integrates seamlessly into mobile POS (mPOS) applications. PayGuardian Android facilitates the transaction process by handling the collection and transmission of sensitive payment information as an out of scope PA-DSS solution, thereby offloading the certification responsibility from merchants and integrators. PayGuardian Android is EMV enabled, handles point to point encryption, and tokenizes all transactions to ensure transaction processing is seamless and secure.

Process Flow

For the App-to-App integration method, the PayGuardian Android application is accessed by starting an activity with an intent which encapsulates a request payload.

PayGuardian Cloud

PayGuardian Cloud API

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

{
"locationID": "your-locationID",
"terminalID": "00000000-0000-0000-0000-000000000000",
"username": "your_user_name",
"password": "your_password",
"merchantAccountCode": "your_merchantAccountCode",
"merchantCode": "your_merchantCode",
"mode": "UAT",
"amount": "10.00",
"softwareVendor": "your_POS_name",
"tenderType": "CREDIT",
"transType": "SALE"
}

PayGuardian Cloud is designed for cloud-based Point-of-Sale systems, and delivers the same scope removal and easy EMV acceptance as other versions of PayGuardian. PayGuardian Cloud is operating system independent, and is installed on the merchant's router as a network appliance.

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)