Integration Guide

API Overview

This document is an integration guide to the PayGuardian Cloud API.

Prerequisites

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

Guide Examples

The examples in this guide are expressed as JSON POST bodies and are all available in the SOAPUI example pack. SOAPUI can be downloaded here. The free, open-source, version of SOAPUI is adequate to run the examples.

SDK Overview

This document is an integration guide to the PayGuardian Cloud SDK in both Java and C#.

Prerequisites

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

The libraries can be downloaded here:

For the JAVA SDK, add the following dependencies to your Project Object Model

<dependencies>
  <dependency>
     <groupId>com.fasterxml.jackson.dataformat</groupId>
     <artifactId>jackson-dataformat-xml</artifactId>
     <version>2.9.8</version>
  </dependency>
  <dependency>
     <groupId>org.apache.commons</groupId>
     <artifactId>commons-lang3</artifactId>
     <version>3.3.2</version>
  </dependency>
</dependencies>

Guide Examples

The examples in this guide are expressed as JSON POST bodies and are all available in the SOAPUI example pack. SOAPUI can be downloaded here. The free, open-source, version of SOAPUI is adequate to run the examples.

The JSON POST request text can be directly converted to a PgRequest object for use in the SDK. For example:

C#

PaymentRequest paymentRequest = new PaymentRequest();

    #region Set PaymentRequest     paymentRequest.TenderType ="";
    paymentRequest.TransType ="";
    paymentRequest.Mode ="";
    paymentRequest.TransIndustryType ="";
    paymentRequest.Amount ="";
    paymentRequest.Headless ="";
    paymentRequest.ManualEntry ="";
    paymentRequest.softwareVendor ="";
    paymentRequest.OrigRefNum ="";
    paymentRequest.convenienceFee ="";
    paymentRequest.InvNum ="";
    paymentRequest.Username ="";
    paymentRequest.Password ="";
    paymentRequest.ClerkID ="";
    paymentRequest.ExtendedSummary ="";
    paymentRequest.Token ="";
    paymentRequest.ServiceFee ="";
    paymentRequest.ExpirationDate ="";
    paymentRequest.forceOnDuplicate ="";
    paymentRequest.TipAmt ="";
    paymentRequest.TaxAmt ="";
    paymentRequest.CashBackAmt ="";
    paymentRequest.BaseURL ="";
    paymentRequest.LocationID ="";
    paymentRequest.TerminalID ="";
    paymentRequest.PONum ="";
    paymentRequest.Street ="";
    paymentRequest.Zip ="";
    paymentRequest.Country ="";
    paymentRequest.ExtData ="";
    paymentRequest.AuthCode ="";
    paymentRequest.sessionId ="";
    paymentRequest.CustomerName ="";
    paymentRequest.MerchantAccountCode ="";
    paymentRequest.MerchantCode ="";
  #endregion

  PaymentPage pg = new PaymentPage();
  pg.PaymentRequest = paymentRequest;

  ShowPageResult result = pg.ShowPage();

  PaymentResponse paymentResponse = new PaymentResponse();
  paymentResponse = pg.PaymentResponse;

  #region PaymentResponse properties example only   SetControlText(control: Resten, value: paymentResponse?.tenderType);
  SetControlText(control: entryMode, value: paymentResponse?.entryMode);
  SetControlText(control: InvNumresponse, value: paymentResponse?.InvNum);
  SetControlText(control: Result, value: paymentResponse?.ResultCode);
  SetControlText(control: ResultMsg, value: paymentResponse?.ResultTxt);
  SetControlText(control: RefNum, value: paymentResponse?.RefNum);
  SetControlText(control: AuthCode, value: paymentResponse?.AuthCode);
  SetControlText(control: AVSResponse, value: paymentResponse?.AVSResponse);
  SetControlText(control: CVResponse, value: paymentResponse?.CVResponse);
  SetControlText(control: Timestamp, value: paymentResponse?.Timestamp);
  SetControlText(control: HostCode, value: paymentResponse?.Hostcode);
  SetControlText(control: RequestedAmt, value: paymentResponse?.RequestedAmount);
  SetControlText(control: CustomerAccountCode, value: paymentResponse?.CustomerAccountCode);
  SetControlText(control: ApprovedAmt, value: paymentResponse?.ApprovedAmount);
  SetControlText(control: RemainingBalance, value: paymentResponse?.RemainingBalance);
  SetControlText(control: HostResponse, value: paymentResponse?.HostResponse);
  SetControlText(control: BogusCardNum, value: paymentResponse?.BogusAccountNumber);
  SetControlText(control: CardType, value: paymentResponse?.CardType);
  SetControlText(control: RequestedAmt, value: paymentResponse?.RequestedAmount);
  SetControlText(control: SubmittedAmt, value: paymentResponse?.SubmittedAmount);
  SetControlText(control: CashBackAmtResponse, value: paymentResponse?.CashBackAmount);
  SetControlText(control: TipAmtResponse, value: paymentResponse?.TipAmount);
  SetControlText(control: ApprovedAmt, value: paymentResponse?.ApprovedAmount);
  SetControlText(control: RemainingBalance, value: paymentResponse?.RemainingBalance);
  SetControlText(control: IsCommercialCard, value: paymentResponse?.IsCommercialCard.ToString());
  SetControlText(control: RespExtData, value: paymentResponse?.receiptTagData);
  SetControlText(control: ServiceFeeResulttxt, value: paymentResponse?.serviceFeeResult?.ToString());
  SetControlText(control: txtCardClass, value: paymentResponse?.CardClass);
  SetControlText(control: txtCardModifier, value: paymentResponse?.CardModifier);
  SetControlText(control: txtCardHolderName, value: paymentResponse?.CardHolderName);
  SetControlText(control: RawResponse, value: paymentResponse?.RawResponse);
#endregion

if (result?.code == ShowPageResultCode.CANCEL)
{
      MessageBox.Show("Action cancelled by user.");
}
else if (result?.code != ShowPageResultCode.OK)
{
      MessageBox("Error: " +paymentResponse.ResultTxt);
}
}
finally
}

}

}

Java

String json_request; /*The json post request text */
String host_name = "https://pgc.bridgepaynetsecuretx.com:443";
Gson gson = new Gson();
PgCloudResponse response = null;

try {
/* Process the request */ PgCloudRequest request = gson.fromJson(json_request, PgCloudRequest.class);
PgCloudConnection con = new PgCloudConnection();
response = con.processRequest(host_name, request);

} catch (JsonSyntaxException ex) {

response = new PgCloudResponse();
response.setResultTxt(PgCloudException.json_format);

}

/* Format the response for neat output */ gson = new GsonBuilder().setPrettyPrinting().disableHtmlEscaping().create();
String formatted_response = gson.toJson(response);

Alternatively, getters and setters exist for in the PgRequest and PgResponse object for each JSON field in the provided examples.

Devices

PAX

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

A920 / A920 PRO
A80
A60
E500
E600
E700
E800
Aries8

Ingenico

Ingenico Tetra Lane device series coming soon

Lane 3000
Lane 5000
Lane 7000
Lane 8000
Link 2500
Move 3000

Terminals intended for use in production must be injected with the Production BridgePay P2PE key.
Terminals intended for use in UAT must be injected with the test BridgePay P2PE key. Please reach out to Integrations or Gateway support for key information.

Request & Response Objects

This section details the full payment request/response objects and gives a description of each element. Every key/value pair is expected to be a string.

Request Object

The request object is a JSON object containing all possible fields of a payment request or a special system function request.

 {
"requestID": "Auto-generated request id - Do not use",
"locationID": "b08dee7b-4cfc-40eb-a12b-598e18c35574",
"terminalID": "TerminalID or 00000000-0000-0000-0000-000000000000 for null",
"mode": "PROD|UAT",

"accountNum": "ACH/Check account number",
"acctType": "R (Credit Card & Branded Debit Cards)|D (Unbranded Debit Cards)|S (Savings)|C (Checking)|F (EBT Food Stamp)|H (EBT Cash Benefit)|G (Gift)|L (Fleet)|K (Check)|A (Cash)",
"allowPartialApproval": "true|false",
"amount": "#####.##",
"authCode": "voice auth",
"authToken": "reserved for future use",
"cashBackAmt": "####### - Sent in via POS or automatically via the amount selected by customer on the terminal.",
"city": "AVS city",
"clerkID": "Employee/Clerk ID",
"convenienceFee": "#####.##",
"country": "Account Address Country Code. ISO 3166-1 alpha-2 codes.",
"customerName": "First M Last",
"customFields": "reserved for future use",
"email": "name@somewhere.com",
"expirationDate": "MMYY",
"extData": { /* Multi-Merchant Fields */ "mmId": "Id of merchant on supported terminal.",
"mmName": "Name of merchant on supported terminal.",
/* 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.*/ "lodgingItems": [{ "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.",
/* 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."
/* Terminal Update Fields */ "terminal": { "uuid": "TerminalID to update",
"name": "arbitrary, friendly name of this terminal",
"emvEnabled": "true|false",
"contactlessEnabled": "true|false",
"signatureEnabled": "true|false" },
/* Location General Settings Update Fields */ "generalSettings": { "name": "Friendly name of location.",
"cashBackEnabled": "true|false - Will terminal prompt for cash back",
"debitEnabled": "true|false - Terminal allows debit",
"removeCardToneEnabled": "true|false - Terminal will beep to alert customer to remove card.",
"selectTenderTypeEnabled": "true|false - Terminal will allow customer to select tender type.",
"cardNotPresentDefaultEnabled": "true|false",
"autoUpdateEnabled": "true|false - Location will automatically update firmware.",
"quickChipEnabled": "true|false - EMV quick chip enabled.",
"preferDebitAmount": "#####.## - Terminal will automatically choose debit if over this amount." },
"property": "requested property key" }, "extendedSummary": "",
"invNum": "Invoice number",
"merchantAccountCode": "Provided by BridgePay",
"merchantCode": "Provided by BridgePay",
"misc1Amt": "#####.##",
"misc2Amt": "#####.##",
"misc3Amt": "#####.##",
"password": "BridgePay password",
"persist": "See persist attribute in BridgeCOMM spec.",
"phone": "xxx-xxx-xxxx",
"pnRefNum": "Reference number from a previous transaction",
"poNum": "Purchase order number",
"registerID": "reserved for future use",
"serverID": "reserved for future use",
"serviceFee": "reserved for future use. Do not use with PAX devices.",
"shippingAmt": "#####.##",
"softwareVendor": "Name of vendor of integrated application.",
"surchargeAmt": "#####.##",
"taxAmt": "#####.##",
"tenderType": "UNKNOWN|CREDIT|DEBIT|CHECK|GIFT|EBT_FOOD|EBT_CASH|END_OF_DAY|FUNCTION",
"tipAmt": "#####" Provided in implied decimal format,
"token": "tokenized card number",
"transCode": "",
"transType": "SALE|SALE_AUTH|CREDIT|REFUND|VOID|TOKENADD|CAPTURE|CAPTURE_ALL|ADJUSTMENT|INCREMENT|ACTIVATE|DEACTIVATE|REACTIVATE|BALANCE",
"username": "BridePay username",
"walletKey": "Base64 string representation of the authentication key created to use the wallet token.",
"walletToken": "Base64 string describing the wallet information. Decoded string is the Site ID, User GUID, Wallet ID, and Payment Method ID",
/* Address Verification Service (AVS) */ "state": "AVS state",
"street": "AVS street",
"zip": "AVS Zip",
}

Response Object

The response object is a JSON object containing all possible fields of a payment response, a special system function response, or an error response.

 {
"requestID": "f90c7c9fc1c90de5694c3fd208b3a4921f11fb74d649df6cf9a829d5",
"nsInternalId": "echoed back from request",
"locationID": "echoed back from request",
"terminalID": "echoed back from request",
"approvedAmount": "Amount, fo the total amount, approved by the processor.",
"authCode": "The transaction authorization code returned from the processor.",
"cardType": "Visa|MasterCard|Discover|AmEx|Diners|JCB|CUP|Bank|Undefined",
"cardClass": "Credit|Debit|Gift|Prepaid|EBT|Fleet|Undefined",
"cardModifier": "FSA|Commercial|FoodStamp|Check|Savings|Cash|Undefined",
"cashBackAmount": "####### - Cash back amount requested.",
"customerAccountCode": "Echoed back, user supplied.",
"cvMessage": "CVV/CVV2 Match Result Message.",
"cvResponse": " CVV/CVV2 Match Result Code.",
"expirationDate": "MMYY",
/* ExtData data structure. Only used for signatureEncoded, or function request, in response. */ "extData": { "signatureEncoded": "Base64 encoded signature image.",
/* Required EMV receipt fields. */ "receiptTagData": { "maskedCard": "Masked card number.",
"chipCardAID": "Chip card application identifier.",
"invoice": "Echo back invNum.",
"seq": "Sequence number.",
"authCode": "Processor authorization code.",
"entryMethod": "Account number entry method.",
"totalAmount": "#######",
"pinVerified": "Pin number verified status."
} /* Collection of terminals returned from a function request. */ "terminals": [{
"uuid": "",
"ip": "",
"make": "",
"model": "",
"firmware": "",
"name": "",
"serial": "",
"emvEnabled": "",
"contactlessEnabled": "",
"signatureEnabled": ""
}], /* Location General Settings returned by function request */ "generalSettings": { "name": "Friendly name of location.",
"cashBackEnabled": "true|false - Will terminal prompt for cash back",
"debitEnabled": "true|false - Terminal allows debit",
"removeCardToneEnabled": "true|false - Terminal will beep to alert customer to remove card.",
"selectTenderTypeEnabled": "true|false - Terminal will allow customer to select tender type.",
"cardNotPresentDefaultEnabled": "true|false",
"autoUpdateEnabled": "true|false - Location will automatically update firmware.",
"quickChipEnabled": "true|false - EMV quick chip enabled.",
"preferDebitAmount": "#####.## - Terminal will automatically choose debit if over this amount." },
"property": "value of requested property key" }
"gatewayMessage": "Message from the gateway.",
"hostCode": "",
"hostResponse": "",
"internalMessage": "Provides more information from the gateway and processor regarding the results of the transaction request.",
"invNum": "Echoed back invoice number",
"isCommercialCard": "reserved for future use",
"isoCountryCode": "",
"isoCurrencyCode": "",
"isoRequestDate": "",
"isoTransactionDate": "",
"maskedAccountNumber": "Masked card or check number.",
"merchantCategoryCode": "",
"message": "",
"message1": "",
"message2": "",
"networkMerchantId": "",
"networkReferenceNumber": "",
"networkTerminalId": "",
"providerResponseCode": "",
"providerResponseMessage": "",
"rawResponse": "",
"refNum": "",
"pnRefNum": "Gateway reference number for this transaction.",
"remainingAmount": "Amount remaining from total requested (partial approval).",
"remainingBalance": "",
"requestedAmount": "Total amount requested.",
"responseTypeDescription": "",
"resultCode": "Gateway result code, 00000 for approval.",
"resultTxt": "Gateway result explanation.",
/* ServiceFeeResult contains elements describing the results of the service fee transaction. */ "serviceFeeResult": "",
"submittedAmount": "See requested amount.",
"tenderType": "Echoed back tender type.",
"timestamp": "",
"tipAmount": "##### - Returns the implied tipAmt in an implied decimal format.",
"token": "Tokenized account number.",
"transactionCode": "Echo back of the transaction code.",
/* AVS response fields */ "avsMessage": "Unipay AVS Match Result Message.",
"avsResponse": "Unipay AVS Match Result Code.",
"streetMatchMessage": "",
"zipMatchMessage": ""
}

Transactions

A transaction is fundamentally identified by a combination of tenderType and transType. A transaction is sent as the body of an https_post to the appropriate endpoint URL. In this guide a transaction will be identified by tendertype_transtype. The basic required fields for any transaction are:

tenderType
transType
username
password
merchantCode
merchantAccountCode
mode
locationId
terminalId

PAX Device Integrations – Specific Transaction Fields

The field value format of both the locationID and terminalID are the same. The location ID to use for PAX integrations can be found on the home screen of the PG cloud app - called the UUID. Please note that on newer versions of the PG Cloud app, you’ll need to swipe left to see the UUID.

Please also note that the terminalID value can match the locationID as shown in the examples below, but the locationID value must always be the UUID value.

Examples:

"locationID": "29887269-D522-4AD2-916D-C22E718BFEF0",
"terminalID": "29887269-D522-4AD2-916D-C22E718BFEF0",

All zeroes can be used for the terminal ID, but not for the locationID.

"locationID": "29887269-D522-4AD2-916D-C22E718BFEF0",
"terminalID": "00000000-0000-0000-0000-000000000000",

Test URL

POST to URL: https://pgc.bridgepaynetsecuretest.com/req/payment
The mode key should always be set to UAT when POSTing to this URL, unless otherwise specified. When using one of BridgePay’s provided SDKs in UAT, set the BaseURL to the following URL: When using one of BridgePay’s provided SDKs in UAT, set the BaseURL to the following URL: https://pgc.bridgepaynetsecuretest.com

Production URL

POST to URL: https://pgc.bridgepaynetsecuretx.com/req/payment
The mode key should always be set to PROD when POSTing to this URL, unless otherwise specified. When using one of BridgePay’s provided SDKs in production, set the BaseURL to the following URL: https://pgc.bridgepaynetsecuretx.com

CREDIT tender type

The CREDIT tender type is used to identify any credit card transaction.

CREDIT: SALE

SALE will charge a credit card and immediately put it into the current open batch for settlement. On the test server, amounts under $5.00 will decline, and amounts over $5.00 will approve. The following example will initialize the terminal "9102C064-F990-41AB-BAD4-C98F33E4C684" at location "C832D913-982C-4256-9895-2DD13BDA5947" for a sale transaction of $17.00.

SALE request example

 {
  "locationID": "9102C064-F990-41AB-BAD4-C98F33E4C684",
  "terminalID": "TerminalID or 00000000-0000-0000-0000-000000000000 for null",
  "merchantAccountCode": "",
  "merchantCode": "",
  "mode": "UAT",
  "amount": "17.00",
  "invNum": "1234",
  "password": "xxxxxx",
  "tenderType": "CREDIT",
  "transType": "SALE",
  "username": "xxxxxx"
}

SALE response example

 {
"requestID": "2aaf2fe8663c561fe7edf5c663b4e7262dd47274bdba13f3daafb207",
"locationID": "echoed back from request",
"terminalID": "echoed back from request",
"approvedAmount": "1700",
"authCode": "830705",
"avsMessage": "",
"avsResponse": "",
"cardType": "Visa",
"cashBackAmt": "",
"cvMessage": "",
"cvResponse": "",
"expirationDate": "0323",
"extData": { "lodgingItems": [],
"receiptTagData": { "maskedCard": "4***********2645",
"chipCardAID": "A0000000031010",
"invoice": "12345678",
"seq": "23dbde68c492a6c2c6b5cbe726d40741",
"authCode": "830705",
"entryMethod": "Chip_Read",
"totalAmount": "1700",
"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": "1700",
"timestamp": "20180628",
"tipAmount": "",
"token": "11110000000400142645",
"transactionCode": "23dbde68c492a6c2c6b5cbe726d40741"
}

SALE DECLINED response example

 {
"requestID": "ca0c5eb913dcd5d63723c54a7be59cb7c9556b7b599d57c56d961960",
"locationID": "echoed back from request",
"terminalID": "echoed back from request",
"approvedAmount": "0",
"authCode": "",
"avsMessage": "",
"avsResponse": "",
"cardType": "Visa",
"cashBackAmt": "",
"cvMessage": "",
"cvResponse": "",
"expirationDate": "0323",
"extData": { "lodgingItems": [],
"receiptTagData": { "maskedCard": "4***********2645",
"chipCardAID": "A0000000031010",
"invoice": "12345678",
"seq": "18464be0604c6e066aa49bb652bf3424",
"authCode": "",
"entryMethod": "Chip_Read",
"totalAmount": "000",
"pinVerified": "NO"
}
},
"gatewayMessage": "D01 - Denied by customer's bank (Issuer Unavailable)",
"gatewayResult": "30032",
"internalMessage": "Denied by customer's bank",
"isCommercialCard": "False",
"isoCountryCode": "840",
"isoCurrencyCode": "USD",
"isoRequestDate": "2018-06-28 15:04:18.557",
"isoTransactionDate": "2018-06-28 15:04:18.557",
"maskedAccountNumber": "4***********2645",
"merchantCategoryCode": "",
"networkMerchantId": "",
"networkReferenceNumber": "",
"networkTerminalId": "",
"pnRefNum": "253271504",
"remainingAmount": "000",
"requestedAmount": "",
"responseTypeDescription": "decline",
"resultCode": "30032",
"resultTxt": "Denied by customer's bank",
"streetMatchMessage": "",
"submittedAmount": "300",
"timestamp": "20180628",
"tipAmount": "",
"token": "11110000000400142645",
"transactionCode": "18464be0604c6e066aa49bb652bf3424"
}

Multi-Merchant SALE example

Note: Multi-Merchant selection is only available on PAX terminals. Other integrations may send full credentials MC and MAC instead.

Multi-Merchant Fields
	Data Element	Data Type	Length	Description
C	mmID	integer	1-2	Required for Multi-Merchant. The Merchant number configured on the terminal. For PAX devices, this value starts at 0 for Merchant1, and increments by one for each additional merchant until the limit of 24.
O	merchantName	string	16	Optional for Multi-Merchant. Can contain letters, numbers, and the following special characters: - # & ( ) !

 {
"terminalID": "C832D913-982C-4256-9895-2DD13BDA5947",
"mode": "UAT",
"amount": "17.00",
"invNum": "1234",
"tenderType": "CREDIT",
"transType": "SALE",

"extData":{
"mmId":{"x"
"mmName":{"xxxxx"
}

CREDIT: SALE_AUTH

SALE_AUTH will authorize a credit card but WILL NOT place in the current open batch for settlement. The authorization must be captured to be put into the current batch. If the batch is closed before the authorization is captured, the card will not be charged and the authorization will be dropped. See CREDIT_CAPTURE.

SALE_AUTH request

 {
"locationID": "3eaddf76-27e6-4883-a49c-0aa876e64734",
"terminalID": "TerminalID, 00000000-0000-0000-0000-000000000000 for null",
"merchantAccountCode": "",
"merchantCode": "",
"mode": "uat",
"amount": "5.00",
"invNum": "12345678",
"password": "xxxxxx",
"tenderType": "CREDIT",
"transType": "SALE_AUTH",
"username": "xxxxxx"
}

SALE_AUTH response

 {
"requestID": "1aeec90f6fd0e75ec574660f687e6ea9d2c7a8993e14b4d86da005cc",
"locationID": "echoed back from request",
"terminalID": "echoed back from request",
"approvedAmount": "5.00",
"authCode": "233191",
"avsMessage": "",
"avsResponse": "",
"cardType": "Visa",
"cashBackAmt": "",
"cvMessage": "",
"cvResponse": "",
"expirationDate": "0323",
"extData": { "lodgingItems": [],
"receiptTagData": { "maskedCard": "4***********2645",
"chipCardAID": "A0000000031010",
"invoice": "12345678",
"seq": "1c5753a3b2f4ec24f55de989187ae765",
"authCode": "233191",
"entryMethod": "Chip_Read",
"totalAmount": "500",
"pinVerified": "NO"
},
"signatureEncoded": "iVBORw0KGgoAAAANSUhEUgAAAe8AAACWCAIAAAB4sZcnAAACzUlEQVR42u3..."
},
"gatewayMessage": "A01 - Approved",
"gatewayResult": "0",
"internalMessage": "Approved: 233191 (approval code)",
"isCommercialCard": "False",
"isoCountryCode": "840",
"isoCurrencyCode": "USD",
"isoRequestDate": "2018-06-28 14:51:33.677",
"isoTransactionDate": "2018-06-28 14:51:33.677",
"maskedAccountNumber": "4***********2645",
"merchantCategoryCode": "",
"networkMerchantId": "",
"networkReferenceNumber": "",
"networkTerminalId": "",
"pnRefNum": "253271404",
"remainingAmount": "000",
"requestedAmount": "",
"responseTypeDescription": "auth",
"resultCode": "0",
"resultTxt": "Successful Request",
"streetMatchMessage": "",
"submittedAmount": "500",
"timestamp": "20180628",
"tipAmount": "",
"token": "11110000000400142645",
"transactionCode": "1c5753a3b2f4ec24f55de989187ae765"
}

CREDIT: CAPTURE

CAPTURE will place an approved SALE_AUTH transaction into the current open batch by using the pnRefNum returned by the SALE_AUTH. This capture can be voided before the batch is closed by using the pnRefNum returned from the CREDIT_CAPTURE request.

CAPTURE request

 {
"locationID": "3eaddf76-27e6-4883-a49c-0aa876e64734",
"terminalID": "TerminalID, 00000000-0000-0000-0000-000000000000 for null",
"merchantAccountCode": "",
"merchantCode": "",
"mode": "uat",
"pnRefNum": "253271404",
"password": "xxxxxx",
"tenderType": "CREDIT",
"transType": "CAPTURE",
"username": "xxxxxx"
}

CAPTURE response

 {
"requestID": "763ba7a40257c5234a3d3a6ce2bc6a2766a0f641edbe2aa4c04804e4",
"locationID": "echoed back from request",
"terminalID": "echoed back from request",
"approvedAmount": "",
"cashBackAmt": "",
"extData": {
"lodgingItems": [],
"receiptTagData": {}
},
"gatewayMessage": "A01 - Approved",
"gatewayResult": "0",
"pnRefNum": "253271404",
"remainingAmount": "",
"requestedAmount": "",
"resultCode": "0",
"resultTxt": "Successful Request",
"submittedAmount": "",
"tipAmount": "",
"transactionCode": "1c5753a3b2f4ec24f55de989187ae765"
}

CAPTURE_ALL

CAPTURE_ALL will close the current open batch and settle all captured transactions within that batch. Any SALE_AUTHs that have not been captured will be discarded.

CAPTURE_ALL request

 {
"locationID": "3eaddf76-27e6-4883-a49c-0aa876e64734",
"terminalID": "TerminalID or 00000000-0000-0000-0000-000000000000 for null",
"username": "xxxxxx",
"password": "xxxxxx",
"merchantAccountCode": "0000000",
"merchantCode": "0000000",
"mode": "UAT",
"tenderType": "CREDIT",
"transType": "CAPTURE_ALL"
}

CAPTURE_ALL response

 {
"requestID": "84672c5f57c5234a3d3a6ce2bc6a2766a0f641edbe2aa4c04804e4",
"locationID": "echoed back from request",
"terminalID": "echoed back from request",
"gatewayMessage": "A01 - Approved",
"gatewayResult": "0",
"resultCode": "0",
"resultTxt": "Successful Request",
"transactionCode": "5c5753a3234s4ec24f55de989187ae765"
}

ACCOUNT_VERIFICATION

Use the Account Verification request to obtain information for a given credit card to return if the card is activate, correct CVV and/or correct zip code. This function returns information like a sale process except it does not charge the card. This is similar to a $0.00 authorization. See Appendix A.1 in the BridgeComm Direct Post API Guide for response code values.

ACCOUNT VERIFICATION request

 {
"locationID": "3eaddf76-27e6-4883-a49c-0aa876e64734",//PG CLOUD ONLY
"terminalID": "TerminalID or 00000000-0000-0000-0000-000000000000 for null",
"invNum": "10",
"tenderType": "CREDIT",
"transType": "ACCOUNT_VERIFICATION",
}

ACCOUNT VERIFICATION response

 {
"requestID": "8458ae0fc93902de32128dbfeb3b50b52574fdae45d3bc9835823558",
"locationID": "echoed back from request",
"terminalID": "echoed back from request",
"approvedAmount": "0",
"authCode": "DSC554",
"cardType": "JCB",
"cashBackAmt": "0",
"entryMode": "Manual",
"expirationDate": "1125",
"extData": {"lodgingItems": [],
  "receiptTagData": {
  "maskedCard": "3***********5859",
  "invoice": "10",
  "authCode": "DSC554",
  "entryMethod": "Manual",
  "totalAmount": "0",
}
},
"gatewayMessage": "Successful Request",
"gatewayResult":"0",
"hostResponse":"00000",
"invNum":"00000",
"maskedAccountNumber":"3***********5859",
"message":"Successful Request",
"rawResponse":"PEFtb3VudER1ZT4wPC9BbW91bnREdWU+PFRpcEFtb3VudD4wPC9UaXBBbW91bnQ+PENhc2hCYWNrQW1vdW50PjA8L0Nhc2hCYWNrQW1vdW50PjxNZXJjaGFudEZlZT4wPC9NZXJjaGFudEZlZT48VGF4QW1vdW50PjA8L1RheEFtb3VudD48UExFbnRyeU1vZGU+MDwvUExFbnRyeU1vZGU+PEV4cERhdGU+MTEyNTwvRXhwRGF0ZT48UExDYXJkUHJlc2VudD4xPC9QTENhcmRQcmVzZW50PjxBVlNNZXNzZ2FlPkFkZHJlc3Mgbm90IGF2YWlsYWJsZSAoQWRkcmVzcyBub3QgdmVyaWZpZWQpPC9BVlNNZXNzZ2FlPjxUb2tlbj4xMTExMDAwMDAwMDA3Mjc1NTg1OTwvVG9rZW4+PFNOPjEzNTAwMjA3ODY8L1NOPjxQUk9HUkFNVFlQRT4wPC9QUk9HUkFNVFlQRT48RURDVFlQRT5DcmVkaXQ8L0VEQ1RZUEU+PENBUkRCSU4+MzUzMDE0PC9DQVJEQklOPjxHbG9iYWxVSUQ+MTM1MDAyMDc4NjIwMjEwOTAzMDY1NDIxNjQyMDwvR2xvYmFsVUlEPg==",
"remainingAmount":"0",
"requestedAmount":"0",
"resultCode":"000000",
"resultTxt":"OK",
"submittedAmount":"0",
"timestamp":"20210903065421",
"tipAmount":"0",
"token":"11110000000072755859",
}

TOKENADD

TOKENADD will tokenize a credit card number and store this token in the gateway for future use. TOKENADD is swipe-only. To use a token in the future the token must be supplied with the correct expiration date.
Note: TOKENADD is only available on Ingenico terminals.

TOKENADD request

 {
"locationID": "3eaddf76-27e6-4883-a49c-0aa876e64734",
"terminalID": "TerminalID, 00000000-0000-0000-0000-000000000000 for null",
"merchantAccountCode": "",
"merchantCode": "",
"invNum": "12345678",
"mode": "uat",
"password": "xxxxxx",
"tenderType": "CREDIT",
"transType": "TOKENADD",
"username": "xxxxxx"
}

TOKENADD response

 {
"requestID": "42bb6a1770dfb7e8f4e3d7083f65db93aa800ea305fb3848603f2ef4",
"locationID": "echoed back from the request",
"terminalID": "echoed back from request",
"approvedAmount": "",
"cashBackAmt": "",
"expirationDate": "1218",
"extData": {"lodgingItems": [],
"receiptTagData": {}
}, "remainingAmount": "",
"requestedAmount": "",
"resultCode": "0",
"resultTxt": "Successful Request",
"submittedAmount": "",
"tipAmount": "",
"token": "1000000044935454"
}

VOID

VOID will void a transaction in the current open batch based upon the supplied pnRefNum.
Note: REFUND can be used in place of VOID. The gateway will switch it to a VOID if the transaction was not been settled.

VOID request

 {
"locationID": "3eaddf76-27e6-4883-a49c-0aa876e64734",
"terminalID": "TerminalID, 00000000-0000-0000-0000-000000000000 for null",
"merchantAccountCode": "",
"merchantCode": "",
"mode": "uat",
"pnRefNum": "253271404",
"amount": "17.00",
"password": "xxxxxx",
"tenderType": "CREDIT",
"transType": "VOID",
"username": "xxxxxx"
}

VOID response

 {
"requestID": "d9061af72f73f118fb9a2558c379066f3249b385028d486d404f0a0d",
"locationID": "echoed back from request",
"terminalID": "echoed back from request",
"approvedAmount": "",
"cashBackAmt": "",
"extData": {"lodgingItems": [],
"receiptTagData": {}
}, "gatewayMessage": "A03 - Void Posted (Auth Reversed)",
"gatewayResult": "0",
"pnRefNum": "253271404",
"remainingAmount": "000",
"requestedAmount": "",
"responseTypeDescription": "void",
"resultCode": "0",
"resultTxt": "Successful Request",
"submittedAmount": "",
"tipAmount": "",
"transactionCode": ""
}

REFUND

REFUND will refund a transaction that has been settled. If the transaction is NOT settled and is in the current open batch, the gateway will then VOID the transaction.

REFUND request

 {
"locationID": "3eaddf76-27e6-4883-a49c-0aa876e64734",
"terminalID": "TerminalID, 00000000-0000-0000-0000-000000000000 for null",
"merchantAccountCode": "",
"merchantCode": "",
"pnRefNum": "253274504",
"amount": "15.00",
"mode":"uat",
"password": "xxxxxx",
"tenderType": "CREDIT",
"transType": "REFUND",
"username": "xxxxxx"
}

REFUND response

 {
"requestID": "38128d5eacd3f3d11600b2b3e6a2a79f3c0decf97fc0a1b44f102b23",
"locationID": "echoed back from request",
"terminalID": "echoed back from request",
"approvedAmount": "",
"cashBackAmt": "",
"extData": {"lodgingItems": [],
"receiptTagData": {}
}, "gatewayMessage": "A03 - Refund Posted",
"gatewayResult": "0",
"pnRefNum": "253274504",
"remainingAmount": "0.00",
"requestedAmount": "",
"responseTypeDescription": "refund",
"resultCode": "0",
"resultTxt": "Successful Request",
"submittedAmount": "",
"tipAmount": "",
"transactionCode": ""
}

ADJUSTMENT

ADJUSTMENT a.k.a. "tip adjust" will adjust a previous SALE 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).

ADJUSTMENT request

 {
"locationID": "3eaddf76-27e6-4883-a49c-0aa876e64734",
"terminalID": "TerminalID, 00000000-0000-0000-0000-000000000000 for null",
"merchantAccountCode": "",
"merchantCode": "",
"pnRefNum": "253276004",
"mode":"uat",
"amount": "5.00",
"password": "xxxxxx",
"tenderType": "CREDIT",
"transType": "ADJUSTMENT",
"username": "xxxxxx"
}

ADJUSTMENT response

 {
"requestID": "388c37acbd88d7f00fce90ffee8b83c156efedb57828c1e8439e6284",
"locationID": "echoed back from request",
"terminalID": "echoed back from request",
"approvedAmount": "2000",
"authCode": "802431",
"avsMessage": "",
"avsResponse": "",
"cardType": "",
"cashBackAmt": "",
"cvMessage": "",
"cvResponse": "",
"expirationDate": "",
"extData": {"lodgingItems": [],
"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": "000",
"requestedAmount": "",
"resultCode": "0",
"resultTxt": "Successful Request",
"streetMatchMessage": "",
"submittedAmount": "1500",
"timestamp": "",
"tipAmount": "",
"token": "",
"transactionCode": ""
}

DEBIT tender type

The DEBIT tender type is used to identify any debit card transaction.

DEBIT: SALE

SALE will charge a debit card (prompting for pin if required) and immediately put it into the current open batch for settlement. The following example includes the customer choosing $20.00 cash back on the terminal. The cash back choice screen will only show on the terminal if the cashBackEnabled flag is set in the general settings. See "6. General Settings".

SALE request

 {
"locationID": "3eaddf76-27e6-4883-a49c-0aa876e64734",
"terminalID": "TerminalID or 00000000-0000-0000-0000-000000000000 for null",
"merchantAccountCode": "",
"merchantCode": "",
"amount": "10.00",
"invNum": "12345678",
"mode": "uat",
"password": "xxxxxx",
"tenderType": "DEBIT",
"transType": "SALE",
"username": "xxxxxx"
}

SALE response

 {
"requestID": "8327f129b18203fa5c2c5ec427672dd267692dcf4988581cf7532c84",
"locationID": "echoed back from request",
"terminalID": "echoed back from request",
"approvedAmount": "3000",
"authCode": "238995",
"avsMessage": "",
"avsResponse": "",
"cardType": "Visa",
"cashBackAmt": "2000",
"cvMessage": "",
"cvResponse": "",
"expirationDate": "0323",
"extData": {"lodgingItems": [],
"receiptTagData": {"maskedCard": "4***********2645",
"chipCardAID": "A0000000031010",
"invoice": "12345678",
"seq": "e838db91dcba54b3becb225b3224dd77",
"authCode": "238995",
"entryMethod": "Chip_Read",
"totalAmount": "3000",
"pinVerified": "OK"
} }, "gatewayMessage": "A01 - Approved",
"gatewayResult": "0",
"internalMessage": "Approved: 238995 (approval code)",
"isCommercialCard": "False",
"isoCountryCode": "840",
"isoCurrencyCode": "USD",
"isoRequestDate": "2018-06-28 17:16:55.723",
"isoTransactionDate": "2018-06-28 17:16:55.723",
"maskedAccountNumber": "4***********2645",
"merchantCategoryCode": "",
"networkMerchantId": "",
"networkReferenceNumber": "",
"networkTerminalId": "",
"pnRefNum": "253277004",
"remainingAmount": "000",
"requestedAmount": "",
"responseTypeDescription": "sale",
"resultCode": "0",
"resultTxt": "Successful Request",
"streetMatchMessage": "",
"submittedAmount": "3000",
"timestamp": "20180628",
"tipAmount": "",
"token": "11110000000400142645",
"transactionCode": "e838db91dcba54b3becb225b3224dd77"
}

GIFT tender type

The GIFT tender type is used to identify any gift card transaction (not branded gift credit cards such as Visa or MC).

GIFT: SALE

SALE will charge a gift card (prompting for pin if required) and immediately process it with the boarded gift card provider.

SALE request

 {
"locationID": "3eaddf76-27e6-4883-a49c-0aa876e64734",
"terminalID": "TerminalID, 00000000-0000-0000-0000-000000000000 for null",

"merchantAccountCode": "",
"merchantCode": "",
"username": "",
"password": "",
"mode": "uat",

"tenderType": "GIFT",
"transType": "SALE",

"amount": "0.01",
"invNum": "54321"
}

SALE response

 {
"requestID": "a69eaa2b732e5d30896ed20cc6fc5c8f82c1c64cb130c888140836fb",
"locationID": "echoed back from request",
"terminalID": "echoed back from request",
"approvedAmount": "001",
"authCode": "421456",
"avsMessage": "",
"avsResponse": "",
"cardType": "",
"cashBackAmt": "",
"cvMessage": "",
"cvResponse": "",
"expirationDate": "",
"extData": {"lodgingItems": [],
"receiptTagData": {}
}, "gatewayMessage": "A01 - Approved",
"gatewayResult": "0",
"internalMessage": "Approved: 421456 (approval code)",
"isCommercialCard": "False",
"isoCountryCode": "840",
"isoCurrencyCode": "USD",
"isoRequestDate": "2018-07-12 12:52:42.547",
"isoTransactionDate": "2018-07-12 12:52:42.547",
"maskedAccountNumber": "",
"merchantCategoryCode": "",
"networkMerchantId": "",
"networkReferenceNumber": "",
"networkTerminalId": "",
"pnRefNum": "258357504",
"remainingAmount": "000",
"requestedAmount": "",
"responseTypeDescription": "sale",
"resultCode": "0",
"resultTxt": "Successful Request",
"streetMatchMessage": "",
"submittedAmount": "001",
"timestamp": "20180712",
"tipAmount": "",
"token": "11110000000383166392",
"transactionCode": "7235ed86b37a93593efc3a521c740913"
}

GIFT: CREDIT

CREDIT will CREDIT an amount and immediately process it with the boarded gift card provider.

CREDIT request

 {
"locationID": "3eaddf76-27e6-4883-a49c-0aa876e64734",
"terminalID": "TerminalID, 00000000-0000-0000-0000-000000000000 for null",

"merchantAccountCode": "297021",
"merchantCode": "297000",
"username": "",
"password": "",
"mode": "uat",

"tenderType": "GIFT",
"transType": "CREDIT",

"amount": "0.01",
"invNum": "1111"
}

CREDIT response

 {
"requestID": "1277c939a11cb7d7f5bbad8699ad4420b04c771b43a9015e4b8ce812",
"locationID": "echoed back from request",
"terminalID": "echoed back from request",
"approvedAmount": "001",
"authCode": "872053",
"avsMessage": "",
"avsResponse": "",
"cardType": "",
"cashBackAmt": "",
"cvMessage": "",
"cvResponse": "",
"expirationDate": "",
"extData": {"lodgingItems": [],
"receiptTagData": {}
}, "gatewayMessage": "A02 - Credit Posted",
"gatewayResult": "0",
"internalMessage": "Credit Posted",
"isCommercialCard": "False",
"isoCountryCode": "840",
"isoCurrencyCode": "USD",
"isoRequestDate": "2018-07-12 13:39:27.92",
"isoTransactionDate": "2018-07-12 13:39:27.92",
"maskedAccountNumber": "",
"merchantCategoryCode": "",
"networkMerchantId": "",
"networkReferenceNumber": "",
"networkTerminalId": "",
"pnRefNum": "258368904",
"remainingAmount": "000",
"requestedAmount": "",
"responseTypeDescription": "credit",
"resultCode": "0",
"resultTxt": "Successful Request",
"streetMatchMessage": "",
"submittedAmount": "001",
"timestamp": "20180712",
"tipAmount": "",
"token": "11110000000383166392",
"transactionCode": "524effa934d27d15311059774b63a8e0"
}

GIFT: BALANCE

BALANCE will attempt return the available balance of a gift card. The balance is returned in the "remainingBalance" field.

BALANCE request

 {
"locationID": "3eaddf76-27e6-4883-a49c-0aa876e64734",
"terminalID": "TerminalID, 00000000-0000-0000-0000-000000000000 for null",

"merchantAccountCode": "297021",
"merchantCode": "297000",
"username": "",
"password": "",
"mode": "uat",

"tenderType": "GIFT",
"transType": "BALANCE"
}

BALANCE response

 {
"requestID": "2346a1e201c426eb611d8882fb72a63865dcecd9eea639f62bf4db51",
"locationID": "echoed back from request",
"terminalID": "echoed back from request",
"approvedAmount": "",
"authCode": "849493",
"avsMessage": "",
"avsResponse": "",
"cashBackAmt": "",
"cvMessage": "",
"cvResponse": "",
"extData": {"lodgingItems": [],
"receiptTagData": {}
}, "gatewayMessage": "A01 - Approved",
"gatewayResult": "0",
"remainingBalance": "30.61",
"requestedAmount": "",
"resultCode": "0",
"resultTxt": "Successful Request",
"submittedAmount": "",
"timestamp": "20180712",
"tipAmount": "",
"token": "11110000000383166392",
"transType": "BalanceInquiry"
}

GIFT: ACTIVATE

ACTIVATE will perform an initial activation, with the specified amount, on a new gift card.

ACTIVATE request

 {
"locationID": "3eaddf76-27e6-4883-a49c-0aa876e64734",
"terminalID": "TerminalID, 00000000-0000-0000-0000-000000000000 for null",

"merchantAccountCode": "297021",
"merchantCode": "297000",
"username": "",
"password": "",
"mode": "uat",

"tenderType": "GIFT",
"transType": "ACTIVATE",

"amount": "200.00"
}

ACTIVATE response

{ "requestID": "2f26a292f7775e798808ed91cbe3fc39a4906545c4358cd3d1e9d70",
"locationID": "echoed back from request",
"terminalID": "echoed back from request",
"approvedAmount": "",
"batchId": "0",
"cashBackAmt": "0.00",
"extData": {"lodgingItems": [],
"receiptTagData": {}
}, "gatewayMessage": "A01 - Approved",
"gatewayResult": "0",

"pnRefNum": "258382504",
"remainingAmount": "",
"requestedAmount": "",
"responseTypeDescription": "Good",
"resultCode": "0",
"resultTxt": "Successful Request",
"submittedAmount": "",
"timestamp": "",
"tipAmount": "",
"transactionCode": "",
"transType": "Activate"
}

GIFT: REACTIVATE

REACTIVATE adds additional funds to an active gift card.

REACTIVATE request

{
"locationID": "3eaddf76-27e6-4883-a49c-0aa876e64734",
"terminalID": "TerminalID, 00000000-0000-0000-0000-000000000000 for null",

"merchantAccountCode": "297021",
"merchantCode": "297000",
"username": "",
"password": "",
"mode": "uat",

"tenderType": "GIFT",
"transType": "REACTIVATE",

"amount": "20.00"
}

REACTIVATE response

{
"requestID": "01699c92b62cdb945ac595659695d78e3550e94d6e5c96519f1f882a",
"locationID": "echoed back from request",
"terminalID": "echoed back from request",
"approvedAmount": "",
"batchId": "0",
"cashBackAmt": "000",
"extData": {"lodgingItems": [],
"receiptTagData": {}
}, "gatewayMessage": "A01 - Approved",
"gatewayResult": "0",
"pnRefNum": "258381704",
"remainingAmount": "",
"requestedAmount": "",
"responseTypeDescription": "Good",
"resultCode": "0",
"resultTxt": "Successful Request",
"submittedAmount": "",
"timestamp": "",
"tipAmount": "",
"transactionCode": "",
"transType": "Reactivate"
}

GIFT: DEACTIVATE

DEACTIVATE will disable a gift card from being used. Some gift card providers do not allow for reactivation. Please check with your provider.

Functions

Functions are a special tender type that can be used to execute administrative functions at a location remotely. These include updating settings, scanning for new terminals, updating properties, etc. Caution should be used because it is possible to permanently disable a network appliance if settings are updated to invalid values. These should only be executed by a BridgePay representative or a network administrator.

Functions can be used by setting the tenderType to FUNCTION and the transType to the function name.

Functions - All Devices

FUNCTION: PING

PING attempts to send a loop-back request to a terminal connected to PayGuardian Cloud verifying the connection.

PING request

{
"locationID": "9ef7c891-deb5-4fb8-afc0-bb25c8390e56",
"terminalID": "TerminalID or 00000000-0000-0000-0000-000000000000 for null",

"mode": "PROD",
"tenderType": "FUNCTION",
"transType": "PING"
}

PING response

 {
"requestID": "01699c92b62cdb945ac595659695d78e3550e94d6e5c96519f1f882a",
"locationID": "echoed back from request",
"terminalID": "echoed back from request",
"extData":{},
"resultCode": "0",
"resultTxt": "Ping Success",
"timestamp": "1616522446042"
}

FUNCTION: FIND_TRANSACTION

FIND_TRANSACTION retrieves transaction details using OrigRefNum (reference number/transaction ID) or InvNum (invoice number).

FIND_TRANSACTION request

{
"locationID": "9ef7c891-deb5-4fb8-afc0-bb25c8390e56",
"terminalID": "TerminalID or 00000000-0000-0000-0000-000000000000 for null",

"mode": "UAT",
"tenderType": "FUNCTION",
"transType": "FIND_TRANSACTION",
"merchantCode": "682000",
"merchantAccountCode": "682001",
"username": "xxxxx",
"password": "xxxxx",
"invNum": "123456",
"pnRefNum": "3960194704"
}

FIND_TRANSACTION response

 {
"requestID": "20aba0ad54fe6c04c627c1aca2c8bf0d9f8eefd8be3445b00b33c00c",
"locationID": "echoed back from request",
"terminalID": "echoed back from request",
"approvedAmount": "850",
"authCode": "856487",
"cardHolderName": "",
"expirationDate": "1226",
"extData":{},
"maskedAccountNumber": "4****9424",
"pnRefNum": "3960194704",
"refNum": "3960194704",
"resultCode": "00000",
"resultTxt": "Successful Request",
"token": "11110000000586619424",
"transType": "Sale"
}

FUNCTION: PUSHFORMS

PUSHFORMS will push the current form pack to a specified terminal. Support for this function varies by terminal model. Use a null terminal ID to push to all terminals visible on the LAN.

PUSHFORMS request

{
"apiKey": "9123dcbb0b42652b0e105956c68d3ca2ff34584f324fa41a29aedd32b883e131",
"locationID": "9ef7c891-deb5-4fb8-afc0-bb25c8390e56",
"terminalID": "TerminalID or 00000000-0000-0000-0000-000000000000 for null",

"mode": "UAT",
"tenderType": "FUNCTION",
"transType": "PUSHFORMS"
}

PUSHFORMS response

 {
"requestID": "e5a6c6425a88e76ffc4bccbd3b6192a202cac7cff29a61159e38f001",
"locationID": "echoed back from request",
"terminalID": "echoed back from request",
"extData":{},
"resultCode": "0"
}

Functions - Ingenico Telium Devices Only (iSC250, iSC480, iPP320, iPP350)

FUNCTION: SAVE_TERMINAL

SAVE_TERMINAL is used to update settings of a specified terminal. Support for this function varies by terminal model.

SAVE_TERMINAL request

{
"locationID": "9ef7c891-deb5-4fb8-afc0-bb25c8390e56",
"terminalID": "TerminalID or 00000000-0000-0000-0000-000000000000 for null",

"mode": "UAT",
"tenderType": "FUNCTION",
"transType": "SAVE_TERMINAL",
  "extData": {
    "terminal": {
    "uuid": "b07d7056-0f37-4aed-a58e-83b81d76ad70",
    "emvEnabled": true,
    "contactlessEnabled": true,
    "signatureEnabled": true
  }
 }
}

SAVE_TERMINAL response

 {
"requestID": "163045d05d81d91c21acdc28cc9c9f4e3e2dc8933b13b8eed140f821",
"locationID": "echoed back from request",
"terminalID": "echoed back from request",
"extData":{"terminals":[ {
  "mac": "54:e1:40:82:1b:cc",
  "uuid": "b07d7056-0f37-4aed-a58e-83b81d76ad70",
  "ip": "192.168.0.223",
  "make": "Ingenico",
  "model": "iSC250",
  "firmware": "BF",
  "name": "BF_iSC250",
  "serial": "81123192",
  "emvEnabled": true,
  "contactlessEnabled": true,
  "signatureEnabled": true
}]},
"resultCode": "0",
"resultTxt": "Success"
}

Dynamic Descriptors

*Reserved for future use. Availability pending processor certification.*

The per transaction text information representing a merchant/business that their customer sees on their bank account or cardholder statement.

Availability pending processor certification. Please check the processor matrix for more information.

DynamicDescriptorText

Optional. Allows update of the billing descriptor on a card holder’s billing statement. Dynamic Descriptor Text is typically the merchant business name.

DynamicDescriptorAddress

Optional. Allows update of the billing descriptor on a card holder’s billing statement. Dynamic Descriptor Address is typically the merchant business address.

DynamicDescriptorCity

Optional. Allows update of the billing descriptor on a card holder’s billing statement. Dynamic Descriptor City is typically the city name in the merchant business address.

DynamicDescriptorCounty

Optional. Allows update of the billing descriptor on a card holder’s billing statement. Dynamic Descriptor County is typically the county name in the merchant business address.

DynamicDescriptorRegion

Optional. Allows update of the billing descriptor on a card holder’s billing statement. Dynamic Descriptor Region is typically the region name in the merchant business address.

DynamicDescriptorPostalCode

Optional. Allows update of the billing descriptor on a card holder’s billing statement. Dynamic Descriptor Postal Code is typically the zip/postal code in the merchant business address.

DynamicDescriptorCountryCode

Optional. Allows update of the billing descriptor on a card holder’s billing statement. Dynamic Descriptor Country Code is typically the Country Code of the merchant business.

DynamicDescriptorEmailAddress

Optional. Allows update of the billing descriptor on a card holder’s billing statement. Dynamic Descriptor Email Address is typically the email address of the merchant business.

Stored Credentials (Card on File)

*Reserved for future use. Availability pending processor certification.*

Required for the Card on File / Stored Credential Mandate when processing a Sale or RepeatSale transaction using a stored credit card value (credit card number or token) after initial setup.

CUSTOMER

Cardholder initiated transaction using a stored credential.

NOTE: Nothing is actually sent for POS Environment Indicator, but the POS Entry mode will be sent as a “10” to the processors.

UNSCHEDULED

Merchant initiated transaction that is not part of any specific Recurring or Installment relationship/contract.

RECURRING or INSTALLMENT

Merchant initiated transaction for either a Recurring or Installment relationship/contract.

Terminal Settings

Terminal settings are properties that are set per terminal. The settings must be updated on each terminal individually using the FUNCTION_SAVE_TERMINAL request.

Device Pairing Settings

Allows a Smart Terminal device to easily pair to a POS integration, eliminating the need to statically store the terminal ID numbers locally.

FSA/Healthcare

Coming soon to PG Cloud

Lodging

Coming soon to PG Cloud

Auto Rental

Coming soon to PG Cloud

Release Notes

PG Cloud

V2.4.13 Coming Soon

Added Contact EMV and Contactless EMV capability to the Ingenico TETRA Lane device series (Lane/3000, Lane/5000, and Lane/7000, Lane/8000). Please note: Processor EMV Certification is in progress. Check the BridgePay Device Matrix for further details.
Added Lodging industry support to PayGuardian Cloud Mobile for the PAX A920, A80, and A60 devices.
Added HSA/FSA Healthcare transactions support to PayGuardian Cloud Mobile for the PAX A920, A80, and A60 devices.
Added support to include for the PAX E and Aries device series (E500, E600, E700, E800, and PAX Aries8).
Added support for Level III transaction processing.
Updated the Bluefin forms to align with Ingenico UIA versions.

V2.4.12

Added the ability to process transactions with Dynamic Descriptors. Reserved for future use. Availability pending processor certification.
Added the ability to process transactions using the new “StoredCredential” transaction type in support of the secure storage of “Card on File” payment information of repeat customers. Reserved for future use. Availability pending processor certification.
Added the ‘Find_Transaction’ transaction type to the PG Cloud Mobile App for use with the PAX device series.
Added the “getPairingCode” and “waitForTerminalPairing” calls to the PG Cloud listener which enables the Location ID to be automatically obtained without manual entry.
Updated the “Tap, Swipe, or Insert” form to comply with the Visa “Tap to pay” program changes for Contactless EMV.

V2.4.11

Added ACH transaction support to PG Cloud.
Added PG Cloud support to the C# SDK.
Added ability to pair PAX devices (A60, A80, and A920) with the MyBridgePay Virtual Terminal device manager.
Added automatic re-start of the PG Cloud app after reboot for the PAX devices (A60, A80, and A920).
Updated the MyBridgePay Virtual Terminal receipts to display all entry modes from the PAX devices (A60, A80, and A920).
Added support to capture a voice authorization transaction to PG Cloud.
Updated all CAPKS keys to the current versions.
Fixed issue with querying the transaction details using the ‘Find_Transaction’ transaction type.
Fixed issue where when the “Back” button was clicked on PG Cloud Mobile, the application automatically exited and closed.

V2.4.10

Added support for the Ingenico TETRA Lane device series (Lane/3000, Lane/5000, and Lane/7000).
Added Contactless EMV capability to the Bluefin P2PE supported Ingenico devices (iSC250, iPP320, iPP350, and ISMPv4).
Added the SkipConfirm field for use in integrations to bypass the ‘Amount Confirmation’ prompt screen on the device.
Added Lodging industry support.
Added HSA/FSA Healthcare industry support.
Added HSA/FSA Healthcare transactions support to PayGuardian Cloud Mobile for the PAX A920, A80, and A60 devices.
Added Signature Capture support to PayGuardian Cloud Mobile for the PAX A920, A80, and A60 devices.
Fixed issue where if ‘Declined’ or ‘No’ was selected on the ‘Confirm Amount’ form, the device was not returning to the Welcome screen.
Fixed issue where the ‘TransIndustryType’ was not being passed with any transaction using a Token.
Added two new optional fields to the Payment Request: TaxIndicator and HolderType, for use in integrations.
Added the TransactionMode field to a transaction as applicable.
Added the SettlementDelay field to the integration method.
Added the ability to process a TokenPay transaction via an integration method.
Added an automated verification/lookup for the current Ingenico UIA version which will prompt a user to upgrade to UIA version 19.02 if an earlier version is found.
Added the ‘Allow Select Tender’ feature for Bluefin P2PE supported devices.
Added the ability to create a new wallet and process transactions via a wallet via an integration.
Updated the device prompt for ‘Gift Card’ to display as ‘Swipe’ on the Gift Card tender form.
Removed the ability to cancel an ‘EMV swiped fallback’ transaction on the device after the EMV card has been swiped.
Fixed issue with the signature truncation on the Bluefin P2PE Ingenico iSC250 device.
Fixed issue where PayGuardian would lockup when the ‘Clear’ button was entered on a manual transaction and the ‘Auto Submit Transactions’ setting was not enabled in Settings.

V2.4.8

Added the captured cardholder signature to display on receipt.
Added optional fields to dynamically display on the receipt only when populated with a value supplied as part of a transaction request processed. Optional Fields are: PO Number, Invoice Number, Customer Account Code, Shipping Amount, and Convenience Fee.
Added the cardholder name field to display on the receipt.
Added the ability to print a single receipt for: Merchant copy only, Customer copy only, or copies of both receipts.
Added option to display the suggested tip amount configuration on receipts.
Added the ability to enter secure TokenAdd transactions manually on the device.
Added ability to process Service Fee transactions in kiosk mode.
Enhanced the configuration options for the Receipt template settings.
Enhanced the installation process to auto-check for previous versions of Ingenico drivers and update to version 3.12.
Enhanced receipt header and footer with boldface type.
Updated various amounts fields on the receipt.
Removed duplicated fields from the receipt: Total Amount, Auth Code, SEQ, Invoice Number, RefNum and TransID.
Fixed an issue with device displaying ‘Approved’ after a manual transaction has been processed.
Fixed issue where the Enable/Disable setting for ‘Display Optional Check Fields’ did not change the Sale screen for checks.
Fixed issue where the Enable/Disable setting for ‘Turn Off Remove Card Tone’ and ‘Enable Quick Chip’ configurations were not functioning correctly on a consistent basis.
Fixed issue where PG Cloud was not submitting a new TransactionID for EMV transactions.
Fixed issue where the ‘Prev’ and ‘Next’ selections on the Trans Date range date picker in the History search were not displayed.

V2.4.7

Added WiFi support for the Ingenico iSMPv4 device.
Added support for Level II transaction processing.
Added ability to configure the Suggested Tip Amount form to display on the Ingenico devices (iPP320, iPP350, iSC250, iSC350, iSC480, and iSMPv4).
Added support for the ‘Find_Transaction’ request type.
Added support to configure settings as ‘Required’ or as optional data entry input values for Zip and/or CVV2 on manually keyed and service fee transactions.
Added support to configure and use the ‘Confirm Amount’ form to itemize the Service Fee or Convenience Fee when included as part of the transaction.
Added ability to configure the Card Present/Card Not Present setting via the PG Cloud API.
Added support to pass back the configured Payment and Fee Line text for Service Fee and Convenience Fee transactions.
PG Cloud Portal – Added reCAPTCHA Version 3 (invisible CAPTCHA) to the login and registration pages.
PG Cloud Portal – Added ability to configure the Pass Back Fee prompt.
PG Cloud Portal – Added ability to configure WiFi support for the Ingenico iSMPv4 device.
PG Cloud Portal – Added ability to configure the Confirm Amount form.
PG Cloud Portal – Added ability to configure the ‘Total’ line on the Confirm Amount form.
PG Cloud Portal – Added ability to remove a terminal from a location group.

More Information

Table of Contents