Integration Guide

API Overview

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

View this guide in Postman: https://documenter.getpostman.com/view/24254550/2s9XxsWbyv

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

Code Block

language	java

<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#

Code Block

language	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

Code Block

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 devices are ethernet based processing terminals and require basic configuration to install PayGuardian Cloud. These steps are defined here:

The following Ingenico Tetra Series devices are currently supported:

Lane 3000
Lane 5000
Lane 7000
Lane 8000

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.

Code Block

 {
"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.

Code Block

 {
"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:

Code Block
"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.

Code Block
"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: SALE

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

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

Code Block

 {
  "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

Code Block

 {
"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

Code Block

 {
"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: - # & ( ) !

Code Block
{ "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

Code Block

 {
"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

Code Block

 {
"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

Code Block

 {
"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

Code Block

 {
"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

Code Block

 {
"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

Code Block

 {
"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

Code Block

 {
"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

Code Block

 {
"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

Code Block

 {
"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

Code Block

 {
"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

Code Block

 {
"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

Code Block

 {
"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

Code Block

 {
"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

Code Block

 {
"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

Code Block

 {
"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

Code Block

 {
"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

Code Block

 {
"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

Code Block

 {
"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

Code Block

 {
"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

Code Block

 {
"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

Code Block

 {
"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

Code Block

 {
"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

Code Block

 {
"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

Code Block

 {
"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

Code Block

 {
"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

Code Block

{ "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

Code Block

{
"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

Code Block

{
"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

Code Block
{ "locationID": "9ef7c891-deb5-4fb8-afc0-bb25c8390e56", "terminalID": "TerminalID or 00000000-0000-0000-0000-000000000000 for null", "mode": "PROD", "tenderType": "FUNCTION", "transType": "PING" }

PING response

Code Block

 {
"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

Code Block

{
"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

Code Block

 {
"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

Code Block

{
"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

Code Block
{ "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

Code Block

{
"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

Code Block

 {
"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

Supported on Cloud

Lodging

Coming soon to PG Cloud

Auto Rental

Supported on Cloud

Table of Contents

Table of Contents

Page Comparison

Versions Compared

Old Version 23

New Version 24

Key

Integration Guide

API Overview

Prerequisites

Guide Examples

SDK Overview

Prerequisites

Guide Examples

C#

Java

Devices

PAX

Ingenico

Request & Response Objects

Request Object

Response Object

Transactions

PAX Device Integrations – Specific Transaction Fields

Test URL

Production URL

CREDIT: SALE

SALE request example

SALE response example

SALE DECLINED response example

Multi-Merchant SALE example

CREDIT: SALE_AUTH

SALE_AUTH request

SALE_AUTH response

CREDIT: CAPTURE

CAPTURE request

CAPTURE response

CAPTURE_ALL

CAPTURE_ALL request

CAPTURE_ALL response

ACCOUNT_VERIFICATION

ACCOUNT VERIFICATION request

ACCOUNT VERIFICATION response

TOKENADD

TOKENADD request

TOKENADD response

VOID

VOID request

VOID response

REFUND

REFUND request

REFUND response

ADJUSTMENT

ADJUSTMENT request

ADJUSTMENT response

DEBIT tender type

DEBIT: SALE

SALE request

SALE response

GIFT tender type

GIFT: SALE

SALE request

SALE response

GIFT: CREDIT

CREDIT request

CREDIT response

GIFT: BALANCE

BALANCE request

BALANCE response

GIFT: ACTIVATE

ACTIVATE request

ACTIVATE response

GIFT: REACTIVATE

REACTIVATE request

REACTIVATE response

GIFT: DEACTIVATE

Functions

Functions - All Devices

FUNCTION: PING

PING request

PING response

FUNCTION: FIND_TRANSACTION