Versions Compared

Version Old Version 5 New Version Current
Changes made by

Jose Bueno

Noah Hippensteel

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

SDK Download:

View file
namePGAndroidSDK_3.0.0.zip

Introduction

Mobile Point‐of‐Sales (mPOS) systems that process sensitive payment information are required to certify their payment applications to the Payment Application Data Security Standard (PA‐DSS). The addition of EMV certification and continued need for both encryption and tokenization has become a concern for both merchants and integrators. Instituting and maintaining these standards requires significant financial and employee resources in order to adhere

Adherence to the Payments Card Industry Data Security Standards (PCI DSS) compliance requirements requires significant financial and employee resources. Subsequently, any changes made in the mPOS system , may require a partial or full recertification, which increases the cost and time to market. BridgePay has engaged these issues through our product line, the Pay Guardian PayGuardian suite, to better serve the needs of our integrators and merchants. PayGuardian Android is a light weight, highly secure Android application that integrates seamlessly into mPOS applications.

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

Image Removed

✅ The mPOS application collects transaction data such as the dollar amount, invoice number, tender type, transaction type, merchant account information, etc…
✅ The mPOS application constructs the transaction request in an XML format upon the selection of the  Process button. (See 3.1.6 Sample Examples)

✅ PayGuardian obtains the card information via the claiming of the mPOS device using the Device USB Host connection (re: Ingenico RBA SDK) and validates the transaction request object.
✅ The mPOS device prompts to swipe or insert the card and transmits the card information to the PayGuardian application, which captures the card data as a swiped or EMV transaction respectively.
✅ PayGuardian constructs the payload request and transmits the transaction request to the Payment Gateway.
✅ PayGuardian transmits the transaction response returned from the Payment Gateway back to the mPOS application.
✅ The mPOS application implementation responds accordingly to the transaction response.

Image Added

Having previously been paired with a supported Bluetooth Low Energy Card Reader,

  1. The host mPOS application will collect and forward transaction data to the PayGuardian instance using a concrete PaymentRequest.

  2. The PayGuardian instance validates the request, and notifies the card reader that there is a pending transaction.

  3. The card reader notifies the mPos application that it is ready via the ReaderRequestDelegate.

  4. The mPOS application prompts the customer to use their payment card/device

  5. The card reader collects the card data and passes it to the PayGuardian instance.

  6. PayGuardian handles all of the communication with the Payment Gateway, returning a PaymentResponse to the mPOS application

Integration Setup

We have created a demonstration project for integrators that can serve as a base for a payment application. Currently, integration is supported only by referencing the SDK libraries in your application.

We provide wrapped versions of the supported device libraries to shield integrators from handling sensitive payment data directly, thereby simplifying compliance requirements. The wrapper abstracts device-specific details, ensuring that sensitive information is managed securely within the SDK. This allows integrators to focus solely on developing their application without needing to directly interact with or secure sensitive payment data.

Prerequisites

  • Android device (min API 26, must support Bluetooth, live internet connection)

  • ID Tech IDTech VP3300 BT

Project Dependencies

In order to simplify testing and distribution, we have created a Core SDK library (pgmobileandroid-n.n.n.aar) and a device wrapper library for each card reader family we support. This ensures that integrators will have a version of the manufacturer’s device library that is compatible with our software.

The example below contains guidance on specific libraries and their usage in the demonstration project and are current as of December 2024.

Note

Android application permission handling is beyond the scope of this document and is the responsibility of the integrator. We have made every effort to ensure that the core SDK functionality does not trigger unwanted or unexpected permissions requests. Use of the nammu library is taken solely at the risk of the integrator.

build.gradle (app)

Code Block
languagekotlin
// Core SDK and device wrapper
implementation(files("libs/pgmobileandroid-3.0.0.aar"))
implementation(files("libs/pg_idt_wrapper-1.0.0.aar"))

// other necessary libraries
implementation("com.google.code.gson:gson:2.11.0")
implementation("com.google.code.ksoap2-android:ksoap2-android:3.6.2")

// provided, optional. 
// This library is unsupported due to age, but is still hosted publicly at https://github.com/tajchert/Nammu
// It is intended for use to smooth out permissions prompts on older, pre APIAndroid 12 devices.
// Integrators should evaluate their specific needs regarding permissions handling. 
implementation(files("libs/nammu-1.0.0.aar"))

// Repo for simplexml - maven(url = "https://oss.sonatype.org/content/repositories/ksoap2-android-releases/")
implementation("org.simpleframework:simple-xml:2.7.1")

// These libraries provide necessary functionality at the level they are compiled at. 
// Do not upgrade past this point at the risk of losing Android compatibility.
implementation("org.simpleframework:simple-xml:2.7.1") {
    exclude(module = "xpp3")
}
implementation("org.apache.commons:commons-lang3:3.15.0")

build.gradle.kts (Project)

Code Block
languagekotlin
repositories {
    google()
    mavenCentral()
    maven(url = "https://oss.sonatype.org/content/repositories/ksoap2-android-releases/")
}

Device Connection

The device wrapper library provides integrators with an implementation of the CardReader interface from the core SDK library. The class name can be expected to be in the format of (device name)Delegate

PayGuardian initialization

The PayGuardian class is implemented as a singleton and accepts an instance of the PayGuardianDelegate interface to bind events. After instantiation and connection to a CardReader, that delegate is passed into the singleton as well.

Code Block
languagejava
public interface CardReaderPayGuardianDelegate {
    intvoid searchForDeviceByNameinitiateTransaction(String name, int timeoutPaymentRequest request);
    void requestCardReadonTransactionStateChanged(DoubleTransactionState amounttransactionState, booleanString isRefundmessage);
    void requestCardReadonReaderStateChanged(DoubleReaderState amountreaderState, boolean isRefund, boolean disableEmv, boolean disableCtlsString message);
    booleanvoid isConnectedonMessageReceived(String message);
    void cancelonResponseReceived(PaymentResponse paymentResponse);
    DeviceDetailsvoid getDeviceDetailsonError(ArrayList<String> errors);
}
Code Block
languagejava
payGuardian    private void attemptConnection(String deviceName) {
        new Thread(() -> {
            // TODO: note that this response pattern is IDTech specific
            runOnUiThread(() -> {
                VP3300Delegate vp3300Delegate = new VP3300Delegate(this, payGuardian.readerResponseDelegate, new Handler(Looper.getMainLooper()));
        = PayGuardian.getInstance();
payGuardian.setDelegate(payGuardianDelegate);

Device Connection

The device wrapper library provides integrators with an implementation of the CardReader interface from the core SDK library. The class name can be expected to be in the format of (device name)Delegate.

Code Block
languagejava
public interface CardReader {
    int searchForDeviceByName(String name, int timeout);
    void requestCardRead(Double amount, boolean isRefund);
    void requestCardRead(Double amount, boolean isRefund, boolean disableEmv, boolean disableCtls);
    boolean isConnected();
    void cancel();
    DeviceDetails getDeviceDetails();
}
Code Block
languagejava
    private void attemptConnection(String deviceName) {
       int rc = vp3300Delegate.searchForDeviceByName(deviceName, 10000);
new Thread(() -> {
            // Please note ifthat (rcthis !=response 0)pattern {is IDTech specific
            runOnUiThread(() -> {
   String message = switch (rc) {        VP3300Delegate vp3300Delegate = new VP3300Delegate(this, payGuardian.readerResponseDelegate, new Handler(Looper.getMainLooper()));
         case 1 -> "Invalid DEVICE_TYPE";   int rc = vp3300Delegate.searchForDeviceByName(deviceName, 10000);
                if case(rc 2 -> "Bluetooth LE is not supported on this device";!= 0) {
                    String message = switch (rc) {
     case 3 -> "Bluetooth LE is not available";            case 1 -> "Invalid DEVICE_TYPE";
                        case 42 -> "Bluetooth LE is not enabled supported on this device";
                        case 53 -> "DeviceBluetooth notLE paired.is Pleasenot pair firstavailable";
                        case default4 -> "Unknown errorBluetooth LE is not enabled";
                    };    case 5 -> "Device not paired. Please pair first";
        viewModel.appendLogMessage(message);                default }-> else {"Unknown error";
                    };
                    viewModel.appendLogMessage(message);
                } else {
                    payGuardian.setCardReader(vp3300Delegate);
                    viewModel.appendLogMessage("Found device " + deviceName);
                }
            });
        }).start();
    }
Info

While testing with the ID Tech VP3300, we found it was helpful to leave it plugged into USB power as the . The Bluetooth Low Energy scheme will frequently put the reader to sleep. Further, it should not be physically plugged into any computing device as that will supersede a Bluetooth request and return BLE those requests to the wired device regardless of the source.

Program Input Object

The following table contains descriptions for the properties of the extension input object. The properties are optional unless otherwise indicated.

Property

Description

Data Type / Min - Max Values

TenderType

Required. Valid values are:
CREDIT
DEBIT
CHECK
EBT_FOODSTAMP
EBT_CASHBENEFIT
GIFT
UNKNOWN

***UNKNOWN is currently only supported for use with the Ingenico devices. 

String;
Min Value = 4;
Max Value = 25

TransType

Required. Valid values are:
SALE: Makes a purchase with a credit card, debit card, or gift card.
SALE_AUTH: Verifies/authorizes a payment amount on a credit card.
CAPTURE: Places a SALE_AUTH (Authorization only) transaction into an open credit card batch.
CAPTURE_ALL: Performs a settlement or batch close.
ADJUSTMENT: Adds or updates the Tip Amount within an eligible Sale transaction.
REFUND: Returns a credit card, debit card, or gift card payment from a settled batch.
VOID: Removes a credit card or gift card transaction from an unsettled batch.
REVERSAL: Removes a credit card transaction from an unsettled batch in ‘real time’.
BALANCEINQUIRY: Performs an inquiry for the remaining card balance against a gift card, EBT Food Stamp, or EBT Cash Benefit transaction.
ACTIVATE: Performs an activation and sets the initial balance of a new gift card.
REACTIVATE: Adds funds to an existing balance of an active gift card.
DEACTIVATE: Permanently terminates an active gift card.
TOKENADD: Generates a token for a credit or gift card.
TOKENPAY_CREATE: Used to send a request for a secure PCI token.
FIND_TRANSACTION: Retrieves transaction details using a Reference Number, Invoice Number, or TransactionID.
ACCOUNT_VERIFICATION: Use to verify the validity of a credit card. 
 

String;
Min Value = 4;
Max Value = 25

TransIndustryType

Optional. Valid values are:
RETAIL,
RESTAURANT,
ECOMMERCE,
DIRECT_MARKETING

Lodging, Auto?

String;
Min Value = 4;
Max Value = 25

Amount

Required. Total transaction amount (includes subtotal, cash back, tax, and tip (Format example: 0000.00)

String;
Min Value = 4;
Max Value = 9

Username

Required. Username of the Merchant

String;
Min Value = 5;
Max Value = 25

Password

Required. Password of the Merchant.

String;
Min Value = 7;
Max Value = 25

Street

Optional. Zip code of billing address.

String;
Min Value = 5;
Max Value = 9

OrigRefNum

Original reference number. Used for follow‐on transactions (e.g., Void, Reversal).

String;
Min Value = 1;
Max Value = 15

Country

 

String;
Min Value = 2;
Max Value = 25

Phone

 

String;
Min Value = 10;
Max Value = 25

Email

 

N/A

MerchantCode

Required. BridgePay Merchant Code.

String;
Min Value = 1;
Max Value = 9

MerchantAccountCode

Required. BridgePay Merchant Account Code.

String;
Min Value = 1;
Max Value = 9

InvNum

Required. POS system invoice/tracking number.

String;
Min Value = 1;
Max Value = 12

ReferenceID

Optional. Can be populated to echo back a variable in the response message.

String;
Min Value = 1;
Max Value = 50

TerminalType

Required. Terminal device type to be used for transaction processing. Valid values are (case-sensitive):
keyed: Keyed transactions, will show the card entry screen.
rbabt: Ingenico Bluetooth (MSR and EMV supported)
rbausb: Ingenico USB (MSR and EMV supported)
unipayiii: ID TECH Vivopay 3300 Audio Jack (MSR and EMV supported)
vivopay: ID TECH Vivipay 3300 USB (MSR and EMV Supported)
minismartii: ID TECH MinismartII (EMV Supported)
chipper2: BBPOS Chipper 2 via audio jack (MSR and EMV supported)
wisepad2: BBPOS WisePad 2 via Bluetooth (MSR and EMV supported)
wisepos: BBPOS WisePOS via Bluetooth (MSR and EMV supported)
wisepos_manual: BBPOS WisePOS Manual via Bluetooth (MSR and EMV supported)
chipper2_bt: BBPOS Chipper 2 via bluetooth (MSR and EMV supported)

String;
Min Value = 1;
Max Value = 25

PartialAuthorization

Optional. Sets the partial authorization flag for a transaction. The default setting is ‘false’ (meaning not active).

String;
Min Value = 4;
Max Value = 5

BankAccountNum

Optional. The bank account number for ACH and Check transactions. 

String;
Max Value = 20

RoutingNum

Optional. The routing number for ACH and Check transactions. Can contain up to 10 numbers. 

String;
Max Value = 10

HolderType

Optional. Single character, either P (Personal account) or O (Organization account). 

String;
Min Value = 0;
Max Value = 1

CardholderName

Optional. Name as it appears on the credit card, debit card, or gift card

Transaction Handling

All transaction calls are made through a direct call to PayGuardian.getInstance().processTransaction or through PayGuardianDelegate.initiateTransaction. The transaction handler will only process a single transaction at a time, and there is no queuing of requests for later processing. Including the payment card information on a transaction will bypass a card read.

Code Block
languagejava
private PaymentRequest buildBasicPaymentRequest() {
    PaymentRequest paymentRequest = new PaymentRequest();
    paymentRequest.setTerminalID(terminalID);
    paymentRequest.setUsername(userName);
    paymentRequest.setPassword(password);
    paymentRequest.setMerchantCode(merchantCode);
    paymentRequest.setMerchantAccountCode(merchantAccountCode);
    paymentRequest.setTenderType(TenderType.Credit.toString());
    return paymentRequest;
}
// This will trigger a card read request
private void sendSale() {
    PaymentRequest paymentRequest = buildBasicPaymentRequest();
    paymentRequest.setMode(PayGuardianMode.Test.toString());
    paymentRequest.setTransType(TransactionType.Sale.toString());
    paymentRequest.setAmount("10.00");
    payGuardianDelegate.initiateTransaction(paymentRequest);
}
// This will be sent directly to the gateway
private void sendManualSale() {
    PaymentRequest paymentRequest = buildBasicPaymentRequest();
    paymentRequest.setMode(PayGuardianMode.Test.toString());
    paymentRequest.setTransType(TransactionType.Sale.toString());
    paymentRequest.setAmount("10.00");
    paymentRequest.setCardNumber("4111111111111111");
    paymentRequest.setExpDate("1225");
    paymentRequest.setCvvNumber("123");
    payGuardianDelegate.initiateTransaction(paymentRequest);
}

Input

  • All fields are assumed to be of type String unless otherwise specified

  • All amount fields will be processed as implied decimals regardless of the input format

  • Allowable date formats are “yyyyMMdd” and “MM/dd/yyyy”

  • Allowable time formats are "HHmmss" and "HHmm"

PaymentRequest

Property

Description

Data Type / Min - Max Values

TenderType

Required. Valid values are:
CREDIT
DEBIT
EBT_FOODSTAMP
EBT_CASHBENEFIT
GIFT,

String;
Min Value = 4;
Max Value = 25

TransType

Required. Valid values are:
SALE: Makes a purchase with a credit card, debit card, or gift card.
SALE_AUTH: Verifies/authorizes a payment amount on a credit card.
CAPTURE: Places a SALE_AUTH (Authorization only) transaction into an open credit card batch.
CAPTURE_ALL: Performs a settlement or batch close.
ADJUSTMENT: Adds or updates the Tip Amount within an eligible Sale transaction.
REFUND: Returns a credit card, debit card, or gift card payment from a settled batch.
VOID: Removes a credit card or gift card transaction from an unsettled batch.
REVERSAL: Removes a credit card transaction from an unsettled batch in ‘real time’.
BALANCEINQUIRY: Performs an inquiry for the remaining card balance against a gift card, EBT Food Stamp, or EBT Cash Benefit transaction.
ACTIVATE: Performs an activation and sets the initial balance of a new gift card.
REACTIVATE: Adds funds to an existing balance of an active gift card.
DEACTIVATE: Permanently terminates an active gift card.
TOKENADD: Generates a token for a credit or gift card.
TOKENPAY_CREATE: Used to send a request for a secure PCI token.
FIND_TRANSACTION: Retrieves transaction details using a Reference Number, Invoice Number, or TransactionID.
ACCOUNT_VERIFICATION: Use to verify the validity of a credit card. 
 

String;
Min Value = 4;
Max Value = 25

TransIndustryType

Optional, defaults to RETAIL if not provided
RETAIL, RESTAURANT, ECOMMERCE, DIRECT_MARKETING, LODGING, CAR_RENTAL, HEALTHCARE

String;
Min Value = 4;
Max Value = 25

Amount

Required. Total transaction amount (includes subtotal, cash back, tax, and tip (Format example: 0000.00)

String;
Min Value = 4;
Max Value = 9

Username

Required. Username of the Merchant

String;
Min Value = 5;
Max Value = 25

Password

Required. Password of the Merchant.

String;
Min Value = 7;
Max Value = 25

Street

Optional. Zip code of billing address.

String;
Min Value = 5;
Max Value = 9

OrigRefNum

Original reference number. Used for follow‐on transactions (e.g., Void, Reversal).

String;
Min Value = 1;
Max Value = 15

Country

Country of billing address

String;
Min Value = 2;
Max Value = 25

Phone

Phone number for the payer

String;
Min Value = 10;
Max Value = 25

Email

Email address for the payer 

N/A

MerchantCode

Required. BridgePay Merchant Code.

String;
Min Value = 1;
Max Value = 9

MerchantAccountCode

Required. BridgePay Merchant Account Code.

String;
Min Value = 1;
Max Value = 9

InvNum

Required. POS system invoice/tracking number.

String;
Min Value = 1;
Max Value = 12

ReferenceID

Optional. Can be populated to echo back a variable in the response message.

String;
Min Value = 1;
Max Value = 2550

CardNumberPartialAuthorization

Optional. Account number of a credit card, debit card, or gift card used when collecting card data outside of PayGuardian (not recommended).Sets the partial authorization flag for a transaction. The default setting is ‘false’ (meaning not active).

String;
Min Value = 4;
Max Value = 5

HolderType

Optional. Single character, either P (Personal account) or O (Organization account). 

String;
Min Value = 10;
Max Value = 191

ExpDateCardholderName

Optional. Expiration date of a Name as it appears on the credit card, debit card, or gift card (required for Token transactions).

String;
Min Value = 41;
Max Value = 425

CvvNumberCardNumber

Optional. Card verification code Account number of a credit card, debit card, or gift card used when collecting card data outside of PayGuardian (not recommended).

String;
Min Value = 31;
Max Value = 419

Memo

Optional. User supplied data. Valid ExpDate

Optional. Expiration date of a credit card, debit card, or gift card (required for Token transactions).

String;
Min Value = 4;
Max Value = 4

CvvNumber

Optional. Card verification code of a credit card, debit card, or gift card used when collecting card data outside of PayGuardian (not recommended).

String;
Min Value = 3;
Max Value = 4

Memo

Optional. User supplied data. Valid values are: alphanumeric, dashes, spaces, and periods.

String;
Min Value = 1;
Max Value = 60

SoftwareVendor

Optional. Name of vendor that developed the software used in transmitting the transaction.

String;
Min Value = 0;
Max Value =

DisableEMVHostingSoftware

Optional. Disables EMV capability on the terminal (Not Recommended)

Boolean

EnableQuickChip

Optional: Enables Quick Chip for EMV transactions (Currently supported only for Ingenico devices)

Boolean

HostingSoftware

Optional.

String;
Min

String;
Min Value = 0;
Max Value = 50

VoiceAuthCode

Optional. Authorization Code for Voice Authorizations only when authorization was achieved outside of the network (by phone or other means).

String;
Min Value = 0;
Max Value = 15

TaxRate

Optional. Processed as implied decimal. 5.5% would be represented as 550. Additional Tax Amount. REQUIRED FOR LEVEL II/III

String;
Min Value = 0;
Max Value = 5

TaxAmount

Optional. Processed as implied decimal. $1.25 would be represented as 125. REQUIRED FOR LEVEL II.

String;
Min Value = 0;
Max Value = 8

TaxIndicator

Optional. Valid values are: P (Provided), N (Not Provided), or E (Exempt). REQUIRED FOR LEVEL II/III.

String;
Min Value = 0;
Max Value = 1

ShipToName

Optional. Shipping address name. REQUIRED FOR LEVEL II/III.

String;
Min Value = 0;
Max Value = 100

ShipToStreet

Optional. Shipping address street. REQUIRED FOR LEVEL II/III.

String;
Min Value = 0;
Max Value = 128

ShipToCity

Optional. Shipping address city. REQUIRED FOR LEVEL II/III.

String;
Min Value = 0;
Max Value = 50

ShipToState

Optional. Shipping address state. REQUIRED FOR LEVEL II/III.

String;
Min Value = 0;
Max Value = 2

ShipToZip

Optional. Shipping address postal code. Accepted formats are Canadian, UK and US (5 and 9 digit variation) postal codes. REQUIRED FOR LEVEL II/III.

String;
Min Value = 0;
Max Value = 15

ShipToCountryCode

Optional. Shipping address country code. REQUIRED FOR LEVEL II/III. ISO 3166-1 alpha-2 codes.

String;
Min Value = 0;
Max Value = 2

ShippingOriginZip

Availability pending processor certification.

Conditional. *** REQUIRED FOR LEVEL III***

Postal code of the origin of the shipment. Accepted formats are Canadian, UK and US (5 and 9 digit variation) postal codes. Alphanumeric characters ONLY (no hyphens or dashes). Alpha characters must be all upper-case.

String;
Min Value = 0;
Max Value = 10

DiscountAmount

Availability pending processor certification.

Conditional. *** REQUIRED FOR LEVEL III***

Processed as implied decimal. $1.25 would be represented as 125. Additional discount amount.

Integer
Min Value = 0;
Max Value = 8

ShippingAmount

Availability pending processor certification.

Conditional. *** REQUIRED FOR LEVEL III***

Processed as implied decimal. $1.25 would be represented as 125. Additional discount amount.

Integer
Min Value = 0;
Max Value = 8

DutyAmount

Availability pending processor certification.

Conditional. *** REQUIRED FOR LEVEL III***

Processed as implied decimal. $1.25 would be represented as 125. Additional discount amount.

Integer
Min Value = 0;
Max Value = 8

TaxInvoiceCode

Availability pending processor certification.

Conditional. *** REQUIRED FOR LEVEL III***

Must be at least 1 and up to 15 characters. When separate VAT invoice is produced within the context of the order, unique identifier of this invoice.

String
Min Value = 0;
Max Value = 15

LocalTaxAmount

Availability pending processor certification.

Conditional. *** REQUIRED FOR LEVEL III***

Processed as implied decimal. $1.25 would be represented as 125. Additional discount amount.

Integer
Min Value = 0;
Max Value = 8

LocalTaxIndicator

Availability pending processor certification.

Conditional. *** REQUIRED FOR LEVEL III***

P (Provided), N (Not Provided), or E (Exempt).

String
Min Value = 0;
Max Value = 1

NationalTaxAmount

Availability pending processor certification.

Conditional. *** REQUIRED FOR LEVEL III***

Processed as implied decimal. $1.25 would be represented as 125. Additional discount amount.

Integer
Min Value = 0;
Max Value = 8

NationalTaxIndicator

Availability pending processor certification.

Conditional. *** REQUIRED FOR LEVEL III***

P (Provided), N (Not Provided), or E (Exempt).

String
Min Value = 0;
Max Value = 1

OrderCode

Availability pending processor certification.

Conditional. *** REQUIRED FOR LEVEL III***

Unique identifier assigned to the order associated with this transaction in submitter's/merchant's front-end/ inventory system.

String
Min Value = 0;
Max Value = 17

OrderDate

Availability pending processor certification.

Conditional. *** REQUIRED FOR LEVEL III***

Date in format YYYYMMDD. Date when the order associated with the transaction was placed.

String
Min Value = 0;
Max Value = 8

CommodityCode

Availability pending processor certification.

Conditional. *** REQUIRED FOR LEVEL III***

Acquirer designated standardized code that classifies the group of items associated with this order/transaction.

String
Min Value = 0;
Max Value = 4

CustomerAccountTaxID

Availability pending processor certification.

Conditional. *** REQUIRED FOR LEVEL III***

VAT registration number of the customer responsible for this transaction.

String
Min Value = 0;
Max Value = 13

ItemCount

Availability pending processor certification.

Conditional. *** REQUIRED FOR LEVEL III***

The number of items included in the “Item” collection.

TBDInt

Item

Availability pending processor certification.

Conditional. *** REQUIRED FOR LEVEL III***

Used to group the line item details as a collection of individual item contents for an item. The “Item” collection is a repeatable tag within a transaction that consists of the following group of elements:

<Item>
<ItemCode>5999</ItemCode>
<ItemCommodityCode>59999</ItemCommodityCode>
<ItemDescription>components</ItemDescription>
<ItemQuantity>1</ItemQuantity>
<ItemUnitCostAmt>100</ItemUnitCostAmt>
<ItemUnitMeasure>ea</ItemUnitMeasure>
<ItemTaxRate>0</ItemTaxRate>
<ItemTaxAmount>0</ItemTaxAmount>
<ItemTaxIndicator>N</ItemTaxIndicator>
<ItemTaxCode>0</ItemTaxCode>
<ItemDiscountRate>0</ItemDiscountRate>
<ItemDiscountAmount>0</ItemDiscountAmount>
<ItemTotalAmount>100</ItemTotalAmount>
<ItemIsCredit>T</ItemIsCredit>
</Item>
 

Collection

ItemCode

Availability pending processor certification.

Conditional - Required when included in "Item" collection.
*** REQUIRED FOR LEVEL III***

Unique identifier assigned to this item in the submitter’s inventory system.

String
Min Value =

Collection<Item>

CashBackAmount

Optional. Processed as implied decimal. $20.00 would be represented as 2000. Amount of money returned to a payment card holder. Used for Sale with cash back transactions.

String;
Min Value = 0;
Max Value = 8

EnableCashBack

Optional. When set to true, prompts for cashback on the device.

Boolean

TipRecipientCode

Optional. Server ID for the customer. 

String;
Min Value = 0;
Max Value = 1215

ItemCommodityCode

Availability pending processor certification.

Conditional - Required when included in "Item" collection.
*** REQUIRED FOR LEVEL III***

Acquirer designated standardized code that classifies this item.

String
Min Value = 0ConvenienceFee

Convenience Fee. (Format example: 0000.00)

The convenience fee is a line Item reference included in a SALE or SALE_AUTH transaction request in which the customer credit or debit card is charged the total sum in the ‘amount’ field where a transaction request contains both the transaction amount + convenience fee in a single transaction.

String;
Max Value = 128

ItemDescription

Availability pending processor certification.

Conditional - Required when included in "Item" collection.
*** REQUIRED FOR LEVEL III***

Short description of the item.

StringServiceFee

Optional. Separate fee that processes to a separate merchant account (the username and password are passed in with the request message) with a SALE or SALE_AUTH transaction in which the customer credit or debit card will be charged the transaction amount on the merchant account of record, and a service fee amount on a separate transaction to the merchant account designated in the request.

ServiceFee

ResellerCode

Reseller ID assigned by the gateway for the Reseller of the Service Fee account.

String;
Min Value = 0;
Max Value = 3525

ItemQuantity

Availability pending processor certification.

Conditional - Required when included in "Item" collection.
*** REQUIRED FOR LEVEL III***

Quantity of item units purchased as part of this transaction. Up to 4 decimal places.

DecimalMerchantCode

Merchant ID assigned by the gateway for the Merchant of the Service Fee.

String;
Min Value = 0;
Max Value = 25

MerchantAccountCode

Merchant Account ID assigned by the gateway for the Merchant Account of the Service Fee.

String;
Min Value = 0;
Max Value = 1225

ItemUnitCostAmt

Availability pending processor certification.

Conditional - Required when included in "Item" collection.
*** REQUIRED FOR LEVEL III***

Processed as implied decimal. $1.25 would be represented as 125. Cost of a single unit of the item.

Integer
Min Value = 0;
Max Value = 12

ItemUnitMeasure

Availability pending processor certification.

Conditional - Required when included in "Item" collection.
*** REQUIRED FOR LEVEL III***

Unit of measure used to quantify the items purchased/refunded (e.g. kg, lb., inch).

String
Min Value = 0;
Max Value = 12

ItemTaxRate

Availability pending processor certification.

Conditional - Required when included in "Item" collection.
*** REQUIRED FOR LEVEL III***

Processed as implied decimal. 5.5% would be represented as 550. Rate of the tax (if any) charged on this item.

StringCardNotPresent

Optional. When set to ‘TRUE’, the transaction is treated as a Card Not Present transaction. Valid values are:

TRUE = Card Not Present
FALSE = Card Present

Boolean

ForceOnDuplicate

Optional. Can force a duplicate transaction to process when set to true. Valid values are:

TRUE = Force duplicate transaction to process
FALSE = Do not process duplicate transaction

Boolean

WalletPaymentMethodID

Optional. The ID provided by the Wallet API for the payment method. When using this field, no other payment identifiers are necessary (i.e. PaymentAccountNumber, Track, BankAccountNum, etc)

NSString;
Max Value = 36

SettlementDelay

Optional. The period for which a Sale-Auth transaction settlement is delayed. 

String;
Min Value = 0;
Max Value = 121

ItemTaxAmount

Availability pending processor certification.

Conditional - Required when included in "Item" collection.
*** REQUIRED FOR LEVEL III***

Processed as implied decimal. $1.25 would be represented as 125. Amount of tax charged for this item.

Integer
Min Value = 0;
Max Value = 8

ItemTaxIndicator

Availability pending processor certification.

Conditional - Required when included in "Item" collection.
*** REQUIRED FOR LEVEL III***

P (Provided), N (Not provided), or E (Exempt).

String
Min Value = 0;
Max Value = 1

ItemTaxCode

Availability pending processor certification.

Conditional - Required when included in "Item" collection.
*** REQUIRED FOR LEVEL III***

Acquirer designated value classifying the tax that was charged for this item.

String
Min Value = 0;
Max Value = 4

ItemDiscountRate

Availability pending processor certification.

Conditional - Required when included in "Item" collection.
*** REQUIRED FOR LEVEL III***

Processed as implied decimal. 5.5% would be represented as 550. Rate of discount (if any) that was applied to this item.

Integer
Min Value = 0;
Max Value = 8

ItemDiscountAmount

Availability pending processor certification.

Conditional - Required when included in "Item" collection.
*** REQUIRED FOR LEVEL III***

CustomFields

Optional. The ability to pass custom user defined fields to the gateway via a XML string. 
Ex: <Current_Location>Florida</Current_Location>

NSString;
Min = 20
Max Value = 500

BridgeCommURL

Optional. The BridgeComm URL can be passed with a transaction request which is used to override the mode selected and passed in the request message and/or in the app. Ex: https://www.bridgepaynetsecuretest.com/paymentservice/requesthandler.svc

URL String

Healthcare

Property

Description

Data Type / Min - Max Values

HealthCareAmt

The portion of the Total Amount spent on healthcare related services or products. Processed as implied decimal. $1.25 would be represented as 125.

String;
Min Value = 4;
Max Value = 9

Implied Decimal

TransitAmt

The portion of the Total Amount spent on healthcare related transportation. Processed as implied decimal. $1.25 would be represented as 125.

String;
Min Value = 4;
Max Value = 9

Implied Decimal

PrescriptionAmt

The portion of the Healthcare Amount spent on prescription drugs or products. Processed as implied decimal. $1.25 would be represented as 125.

String;
Min Value = 4;
Max Value = 9

Implied Decimal

VisionAmt

The portion of the Healthcare Amount spent on vision related medical services. Processed as implied decimal. $1.25 would be represented as 125.

Amount of tax charged for this item.Integer

String;
Min Value =

0

4;
Max Value =

8

9

ItemTotalAmount

Availability pending processor certification.

Conditional - Required when included in "Item" collection.
*** REQUIRED FOR LEVEL III***

Implied Decimal

DentalAmt

The portion of the Healthcare Amount spent on dental related medical services. Processed as implied decimal. $1.25 would be represented as 125

. Amount of tax charged for this item

.

Integer

String;
Min Value =

0

4;
Max Value =

8

CashBackAmount

Optional.

9

ItemIsCredit

Availability pending processor certification.

Conditional - Required when included in "Item" collection.
*** REQUIRED FOR LEVEL III***

True = T (Item is being returned), F = False (Default if not passed - Item is being purchased).

String
Min Value = 0;
Max Value = 1

Implied Decimal

ClinicAmt

The portion of the Healthcare Amount spent on hospitalization. Processed as implied decimal.

$20

$1.

00

25 would be represented as

2000. Amount of money returned to a payment card holder. Used for Sale with cash back transactions.

125.

String;
Min Value =

0

4;
Max Value =

8

EnableCashBack

Optional. When set to true, prompts for cashback on the device.

Boolean

EnforceCardType

Optional. When set to true, prompts for Credit/Debit filtering.

Boolean

TipRecipientCode

Optional. Server ID for the customer. 

String;
Min Value = 0;
Max Value = 15

PushTipForm

Conditional. Required only when using ‘QueryTip’ function. This function is used to push the ‘Tip Query’ form to the terminal for first time use.

Boolean

QueryTip

Conditional. When set to true, prompts for tip amount entry on the device. Requires pre-requisite form push of the ‘PushTipForm’ function to the terminal for first time use.

Boolean

PushForms

Conditional. Required only when using 'QueryTip', 'AmountConfirmatin', and/or 'Unknown Tender' functions. This function is ued to push the forms to the terminal for first time use. (Use is only for Ingenico Devices)

Boolean

PushTenderForm

Conditional. Required only when using the ‘UNKNOWN’ tender type. This function is used to push the ‘Select Tender’ form to the terminal for first time use.

Boolean

EnableConfirmAmount

Optional. Flag to enable the Amount confirmation; does require a form push. (Use is only for Ingenico Devices)  

Boolean

ConvenienceFee

Convenience Fee. (Format example: 0000.00)

The convenience fee is a line Item reference included in a SALE or SALE_AUTH transaction request in which the customer credit or debit card is charged the total sum in the ‘amount’ field where a transaction request contains both the transaction amount + convenience fee in a single transaction.

String;
Max Value = 8

ServiceFee

Optional. Separate fee that processes to a separate merchant account (the username and password are passed in with the request message) with a SALE or SALE_AUTH transaction in which the customer credit or debit card will be charged the transaction amount on the merchant account of record, and a service fee amount on a separate transaction to the merchant account designated in the request.

Format: XML String containing ServiceFeeID, Amount, ServiceUser, and Password.

Format example:
<ServiceFee>
<ServiceFeeID>1</ServiceFeeID>
<ResellerCode></ResellerCode>
<MerchantCode></MerchantCode>
<MerchantAccountCode></MerchantAccountCode>
<Amount>800</Amount>
<ServiceUser>testuser</ServiceUser>
<ServicePassword>Testpassword!</ServicePassword>
</ServiceFee>

X

ServiceUser

User name of the Service Fee Merchant Account.

String;
Min Value = 4;
Max Value = 25

ServicePassword

Password of the ServiceUser.

String;
Min Value = 4;
Max Value = 25

ResellerCode

Reseller ID assigned by the gateway for the Reseller of the Service Fee account.

String;
Min Value = 0;
Max Value = 25

MerchantCode

Merchant ID assigned by the gateway for the Merchant of the Service Fee.

String;
Min Value = 0;
Max Value = 25

MerchantAccountCode

Merchant Account ID assigned by the gateway for the Merchant Account of the Service Fee.

String;
Min Value = 0;
Max Value = 25

CardNotPresent

Optional. When set to ‘TRUE’, the transaction is treated as a Card Not Present transaction. Valid values are:

TRUE = Card Not Present
FALSE = Card Present

Boolean

ForceOnDuplicate

Optional. Can force a duplicate transaction to process when set to true. Valid values are:

TRUE = Force duplicate transaction to process
FALSE = Do not process duplicate transaction

Boolean

DisableContactless

Optional. Disable contactless EMV transactions from processing. When set to true, the contactless interface on the Ingenico devices (iCMP, iSMP, iPP320, and iPP350) is disabled.

TRUE = Disables contactless (Default)
False = Enables contactless

Boolean

ConfigureVivopay

Optional. Push config file settings to device (one-time setup). 

True = push config file
False = no config (Default)

Boolean

WalletPaymentMethodID

Optional. The ID provided by the Wallet API for the payment method. When using this field, no other payment identifiers are necessary (i.e. PaymentAccountNumber, Track, BankAccountNum, etc)

NSString;
Max Value = 36

Wallet

Optional. The ability to create a wallet within processing a request by setting: <Wallet>new</Wallet>

NSString;
Max Value = 3

SettlementDelay

Optional. The period for which a Sale-Auth transaction settlement is delayed. 

String;

9

Implied Decimal

Lodging

Property

Description

Data Type / Min - Max Values

RoomNumber

Hotel room number

25

FolioNumber

Hotel folio number
Required when LodgingChargeType = 'H'

8

RoomRateAmount

Daily room rate. Implied decimal.
Required when LodgingChargeType = 'H'

4

RoomTaxAmount

Tax charged on daily rate. Implied decimal.

8

LodgingChargeType

Required, type of service for which this transaction is processed.
H = Hotel
R = Restaurant
G = Gift Shop
S = Health Spa
B = Beauty Shop
F = Convention Fee
T = Tennis
O = Golf

1

CheckInDate

Required when LodgingChargeType = 'H'

10

CheckOutDate

Required when LodgingChargeType = 'H'

10

StayDuration

Indicates the length of anticipated, actual or incremental stay.

8

SpecialProgramType

Required when LodgingChargeType = 'H'

Important when the cardholder did not stay at the hotel.
AD = Advance deposit
AR = Assured reservation
DC = Delayed charge
ES = Express service
NC = Normal charge
NS = No show charge

2

DepartureAdjAmount

Additional amount charged after the cardholder left the hotel. Implied decimal.

8

LodgingItemCount

Required if lodging items present in request.

Integer

LodgingItems

The lodgingItems object. See more detail below.

Collection<LodgingItem>

Car Rental

Property

Description

Data Type / Min - Max Values

RentalAgreementNumber

Car Rental Agreement Number. Required as part of the Rental Key.

25

RentalDuration

Required, Car Rental Period in Days

4

RentalName

Required, Name of the person who rented the car

20

RentalState

State where the car rental starts

3

RentalCity

City where the car rental starts

25

RentalCountryCode

Two-character country code for the country in which the car rental starts

2

RentalDailyRateAmount

Total rent amount per mile as an implied decimal

8

RentalExtraChargesAmount

Total dollar amount of extraChargeItems as an implied decimal

8

RentalInsuranceAmount

Car insurance amount as an implied decimal

8

MaxFreeMiles

Total mileage for rental period

8

MileRateAmount

Total rent amount per mile as an implied decimal

8

TotalMiles

Rented car total mileage (miles on car)

8

RentalDate

Required, Date when the car rental starts. (YYYY-MM-DD format)

10

RentalTime

Car rental start time in 24-hour format. (HHMM format)

4

ReturnCity

City where the car is returned

25

ReturnState

State where the car is returned

3

ReturnLocationCode

Identification code of the place where car was returned

10

ReturnCountryCode

Two-character country code for the country where the car is returned

3

ReturnDate

Required, Date when the car should be returned

10

ReturnTime

Time when the car should be returned in 24hour format. (HHMM format)

4

RentalSpecialProgramType

Required, string based enum representing the special program type for the rental.

Accepted values are AD (Advance Deposit), AR (Assured Reservation),
DC (Delayed Charge), ES (Express Service), NC (Normal Charge),
and NS (No Show Charge).

2

RentalExtraChargeItemCount

The number of extra charges in the RentalExtraChargeItem list.

Integer

RentalExtraChargeItem

List of extra charges (see table below for more information)

Collection<RentalExtraChargeItem>

Additional Input Classes

Item

Property

Description

Data Type / Min - Max Values

ItemCode

Availability pending processor certification.

Conditional - Required when included in "Item" collection.
*** REQUIRED FOR LEVEL III***

Unique identifier assigned to this item in the submitter’s inventory system.

String
Min Value = 0;
Max Value =

1Reserved for future use.

12

CustomFields

Optional. The ability to pass custom user defined fields to the gateway via a XML string. 
Ex: <Current_Location>Florida</Current_Location>

NSString;
Min = 20
Max Value = 500

CustomFields

ItemCommodityCode

Availability pending processor certification.

Conditional - Required when included in "Item" collection.
*** REQUIRED FOR LEVEL III***

Acquirer designated standardized code that classifies this item.

String
Min Value = 0;
Max Value = 12

ItemDescription

Availability pending processor certification.

 

Optional. Valid Values are:

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
BridgeComm was enhanced to allow this field as input* Merchant initiated transaction for either a Recurring or Installment relationship/contract.

String;
Min = 0
Max Value = 14

BridgeCommURL

Optional. The BridgeComm URL can be passed with a transaction request which is used to override the mode selected and passed in the request message and/or in the app. Ex: https://www.bridgepaynetsecuretest.com/paymentservice/requesthandler.svc

URL String

Program Output Object

The following table contains descriptions for the PaymentResponse output object properties.

Note: You should only look at the results in the PaymentResponse

Property

Description

Data Type / Min - Max Values

AuthCode

Transaction authorization code from the payment processor. This value is an approval code for approved transactions or an error code/message for declined transactions.

String;
Max Value = 15

ApprovedAmount

The actual amount approved by host. This may differ from the requested amount.

String;
Max Value = 15

AvsResponse

AVS response. See AVS Response Codes(3.1.6 Examples) for a list of possible responses.

String;
Max Value = 10

BogusAccountNumber

Partially masked card number. The first 6 and last 4 digits of the card number are present with zeros in between. This card number will not pass the mod 10 check.

String;
Max Value = 20

CardType

Displays the card type (determined by BIN range).

List of items:

Visa, Mastercard, Discover, Amex, Diners, JCB, CUP (China Union Pay), Bank, None

String;
Max Value = 20

CardModifier

Displays the featured function submitted in addition to the tender type used to process a transaction.

List of items:

Business, FSA, Commercial, FoodStamp, Check, Savings, Cash, None

String;
Max Value = 10

CardClass

Displays the tender type used to process a transaction.

List of items:

Credit, Debit, Gift, Prepaid, EBT, Fleet, None

String;
Max Value = 10

CvResponse

The CV response code. See CV Response Codes on pages 38 for a list of possible responses.

String;
Max Value = 10

RefNum

Gateway reference/PnRef number. Used for follow‐on transactions (i.e., Void, Reversal).

String;
Max Value = 15

RemainingBalance

Remaining balance on gift or prepaid card.

String;
Max Value = 15

RequestedAmount

Original requested amount of the transaction.

String;
Max Value = 15

ResultCode

Result code of the transaction. See on page 35 for more information.

String;
Max Value = 10

ResultTxt

Details from the processor or payment gateway about the transaction result.

String;
Max Value = 15

Timestamp

Time and date of the transaction.

String;
Max Value = 30

ExpirationDate

Echo back of the expiration date.

String;
Max Value = 4

GatewayMessage

Message from the gateway.

String;
Max Value = 30

InternalMessage

Detailed information provided by the gateway / processor regarding results of the transaction request.

String;
Max Value = 50

AVSMessage

Unipay AVS Match Result Message.

String;
Max Value = 10

CVMessage

Unipay CVV/CVV2 Match Result Message.

String;
Max Value = 10

IsoCountryCode

Country code from the gateway.

String;
Max Value = 10

IsoRequestDate

Requested date from the gateway.

String;
Max Value = 10

NetworkReferenceNumber

Gateway Network reference number.

String;
Max Value = 15

MerchantCategoryCode

Merchant Category Code from the gateway.

N/A

NetworkMerchantId

Merchant id from the gateway.

N/A

NetworkTerminalId

Network terminal id from the gateway.

N/A

ResponseTypeDescription

 

N/A

StreetMatchMessage

 

N/A

ExtData

Returns extra data for the extended data fields submitted in the processed transaction (multiple field information may be returned in XML format).

N/A

Token

Represents the tokenized card number received from a token request or authorization.

String;
Max Value = 22

Memo

Conditional. Present if user previously supplied data.

String;
Max Value = 60

ServiceFeeResult

Returns result for Service Fee transactions. Data may be populated in multiple fields and returned in XML format.

String; XML

EntryMode

Returns back the card entry method: Swipe, EMV, Tap.

String;

WalletID

Returns the wallet ID. 

String;
Max Value = 36

WalletPaymentMethodID

Returns the wallet payment method ID.

String;
Max Value = 36

WalletResponseMessage

Returns the wallet response message.

String;
Max Value = 100

WalletResponseCode

Returns the wallet response code. 

String;
Max Value = 2

PayGuardian Android XML Data Format

Familiarity of the DLL interface, its properties and its uses is must, and it is the basis of the PayGuardian Android XML format. A request contains a PaymentRequest root tag and nested data elements containing DLL properties as tags. The response XML has a similar framework containing all of the standard response data.

Examples

Basic transaction request / response and receipt output examples.

MSR Sale Type Request

An example of a basic MSR sale transaction request.

Code Block
payGuardian = new com.bpn.payguardian.android.PayGuardian(getApplicationContext(), this, this);

PaymentRequest paymentRequest = new PaymentRequest();
paymentRequest.setTerminalType(PayGuardian.TERMINAL_TYPE_RBAUSB);
paymentRequest.setUsername("USERNAME");
paymentRequest.setPassword("PASSWORD");
paymentRequest.setMerchantCode("MERCHANT_CODE");
paymentRequest.setMerchantAccountCode("MERCHANT_ACCOUNT_CODE");
paymentRequest.setInvNum("1234");
paymentRequest.setAmount("5.00");
paymentRequest.setTenderType(PayGuardian.TenderTypes.CREDIT.getType());
paymentRequest.setTransType(PayGuardian.TransactionTypes.SALE.getType());

boolean started = payGuardian.processTransaction(paymentRequest, “TEST”);

 
     \
MSR Sale Type Response

An example of a basic MSR sale transaction response.

Code Block
@Override
public void transactionResponse(PaymentResponse response)
{

    //handle response
    }
    response = {PaymentResponse@21368}
    AVSMessage = null
    CVMessage = null
    approvedAmount = {String@21410} "500"
    authCode = {String@21411} "101400"
    avsResponse = null
    bogusAccountNumber = {String@21412} "************9269"
    cardType = null
    cashBackAmount = null
    cvResponse = null
    expirationDate = {String@21413} "0325"
    extData = null
   gatewayMessage = {String@21414} "A01 - Approved"
    gatewayResult = null
   hostCode = null
    hostResponse = null
    internalMessage = {String@21415} "Approved: 101400 (approval code)"
    isCommercialCard = {String@21416} "False"
    isoCountryCode = null
    isoCurrencyCode = null
    isoRequestDate = null
    isoTransactionDate = null
    merchantCategoryCode = null
    message = null
    message1 = null
    message2 = null
    networkMerchantId = null
    networkReferenceNumber = null
    networkTerminalId = null
    rawResponse = null
    refNum = {String@21417} "217228301"
    remainingAmount = {String@21418} "000"
    remainingBalance = null
    requestAmount = null
    responseTypeDescription = null
    resultCode = {String@21419} "00000"
    resultTxt = {String@21420} "Successful Request"
    streetMatchMessage = null
    submittedAmount = {String@21421} "500"
    timeStamp = {String@21422} "20161230"
    tipAmount = null
    token = {String@21423} "11110000000077149269"
    transactionCode = null
MSR Sale Receipt

An example of the values returned on a basic MSR Sale receipt.

Code Block
BPNPayment.BPNReceipt:
  maskedCardNumber: 5***********0608:
  invoice: 8888
  seq: 8888
  authorizationCode: 290144
  entryMethod: Swipe_Read
  totalAmount: 55
  appLabel:
  cardHolderName: (null)
  networkMerchantId: 518564010126944
  networkTerminalId: PPB01.
  cardFirstFour: 5413
  cardType: Mastercard
  requiresSignature: YES
  pinEntered: NO
Sale_Auth Transaction Type Request

An example of a basic authorization only transaction request.

Code Block
payGuardian = new com.bpn.payguardian.android.PayGuardian(getApplicationContext(), this, this);

PaymentRequest paymentRequest = new PaymentRequest();
paymentRequest.setTerminalType(PayGuardian.TERMINAL_TYPE_RBAUSB);
paymentRequest.setUsername("USERNAME");
paymentRequest.setPassword("PASSWORD");
paymentRequest.setMerchantCode("MERCHANT_CODE");
paymentRequest.setMerchantAccountCode("MERCHANT_ACCOUNT_CODE");
paymentRequest.setInvNum("1234");
paymentRequest.setAmount("5.00");
paymentRequest.setTenderType(PayGuardian.TenderTypes.CREDIT.getType());
paymentRequest.setTransType(PayGuardian.TransactionTypes.SALE_AUTH.getType());

boolean started = payGuardian.processTransaction(paymentRequest, “TEST”);
Sale_Auth Transaction Type Response

An example of a basic authorization only transaction response.

Code Block
@Override
public void transactionResponse(PaymentResponse response)
{

    //handle response
    }

    response = {PaymentResponse@21365}
    AVSMessage = null
    CVMessage = null
    approvedAmount = {String@21406} "500"
    authCode = {String@21407} "842171"
    avsResponse = null
    bogusAccountNumber = {String@21408} "************9269"
    cardType = null
    cashBackAmount = null
    cvResponse = null
    expirationDate = {String@21409} "0325"
    extData = null
    gatewayMessage = {String@21410} "A01 - Approved"
    gatewayResult = null
    hostCode = null
    hostResponse = null
    internalMessage = {String@21411} "Approved: 842171 (approval code)"
    isCommercialCard = {String@21412} "False"
    isoCountryCode = null
    isoCurrencyCode = null
    isoRequestDate = null
    isoTransactionDate = null
    merchantCategoryCode = null
    message = null
    message1 = null
    message2 = null
    networkMerchantId = null
    networkReferenceNumber = null
    networkTerminalId = null
    rawResponse = null
    refNum = {String@21413} "217228401"
    remainingAmount = {String@21414} "0"
    remainingBalance = null
    requestedAmount = null
    responseTypeDescription = null
    resultCode = {String@21415} "00000"
    resultTxt = {String@21416} "Successful Request"
    streetMatchMessage = null
    submittedAmount = {String@21417} "500"
    timeStamp = {String@21418} "20161230"
    tipAmount = null
    token = {String@21419} "11110000000077149269"
    transactionCode = null
Sale_Auth Receipt

An example of the values returned on a basic authorization only receipt.

Code BlockBPNPayment.BPNReceipt: maskedCardNumber: 4***********9269: chipCardAID: A0000000031010 invoice: 33333 seq: 33333 authorizationCode: 786986 entryMethod: Chip_Read totalAmount: 75 appLabel: VISA DEBIT cardHolderName: CARDHOLDER/VALUED networkMerchantId: 518564010126944 networkTerminalId: PPB01. cardFirstFour: 4204 cardType: Visa requiresSignature: YES pinEntered: NO

Conditional - Required when included in "Item" collection.
*** REQUIRED FOR LEVEL III***

Short description of the item.

String
Min Value = 0;
Max Value = 35

ItemQuantity

Availability pending processor certification.

Conditional - Required when included in "Item" collection.
*** REQUIRED FOR LEVEL III***

Quantity of item units purchased as part of this transaction. Up to 4 decimal places.

Decimal
Min Value = 0;
Max Value = 12

ItemUnitCostAmt

Availability pending processor certification.

Conditional - Required when included in "Item" collection.
*** REQUIRED FOR LEVEL III***

Processed as implied decimal. $1.25 would be represented as 125. Cost of a single unit of the item.

String
Min Value = 0;
Max Value = 12

ItemUnitMeasure

Availability pending processor certification.

Conditional - Required when included in "Item" collection.
*** REQUIRED FOR LEVEL III***

Unit of measure used to quantify the items purchased/refunded (e.g. kg, lb., inch).

String
Min Value = 0;
Max Value = 12

ItemTaxRate

Availability pending processor certification.

Conditional - Required when included in "Item" collection.
*** REQUIRED FOR LEVEL III***

Processed as implied decimal. 5.5% would be represented as 550. Rate of the tax (if any) charged on this item.

String
Min Value = 0;
Max Value = 12

ItemTaxAmount

Availability pending processor certification.

Conditional - Required when included in "Item" collection.
*** REQUIRED FOR LEVEL III***

Processed as implied decimal. $1.25 would be represented as 125. Amount of tax charged for this item.

Integer
Min Value = 0;
Max Value = 8

ItemTaxIndicator

Availability pending processor certification.

Conditional - Required when included in "Item" collection.
*** REQUIRED FOR LEVEL III***

P (Provided), N (Not provided), or E (Exempt).

String
Min Value = 0;
Max Value = 1

ItemTaxCode

Availability pending processor certification.

Conditional - Required when included in "Item" collection.
*** REQUIRED FOR LEVEL III***

Acquirer designated value classifying the tax that was charged for this item.

String
Min Value = 0;
Max Value = 4

ItemDiscountRate

Availability pending processor certification.

Conditional - Required when included in "Item" collection.
*** REQUIRED FOR LEVEL III***

Processed as implied decimal. 5.5% would be represented as 550. Rate of discount (if any) that was applied to this item.

Integer
Min Value = 0;
Max Value = 8

ItemDiscountAmount

Availability pending processor certification.

Conditional - Required when included in "Item" collection.
*** REQUIRED FOR LEVEL III***

Processed as implied decimal. $1.25 would be represented as 125. Amount of tax charged for this item.

Integer
Min Value = 0;
Max Value = 8

ItemTotalAmount

Availability pending processor certification.

Conditional - Required when included in "Item" collection.
*** REQUIRED FOR LEVEL III***

Processed as implied decimal. $1.25 would be represented as 125. Amount of tax charged for this item.

Integer
Min Value = 0;
Max Value = 8

ItemIsCredit

Availability pending processor certification.

Conditional - Required when included in "Item" collection.
*** REQUIRED FOR LEVEL III***

True = T (Item is being returned), F = False (Default if not passed - Item is being purchased).

String
Min Value = 0;
Max Value = 1

ServiceFee

Property

Description

Data Type / Min - Max Values

Amount

Processed as implied decimal. $1.25 would be represented as 125.

String;
Min Value = 4;
Max Value = 9

Implied Decimal

ServiceUser

The username associated with the merchant service fee account. Use if not providing ResellerCode, MerchantCode and MerchantAccountCode.

String;
Min Value = 5;
Max Value = 25

ServicePassword

The password associated with the merchant service fee account. Use if not providing ResellerCode, MerchantCode and MerchantAccountCode.

String;
Min Value = 7;
Max Value = 25

MerchantCode

The code of the service merchant group.

String;
Min Value = 1;
Max Value = 9

MerchantAccountCode

The code of the service merchant account.

String;
Min Value = 1;
Max Value = 9

ResellerCode

The code of the reseller that owns the service merchant account.

String;
Min Value = 1;
Max Value = 9

LodgingItem

Property

Description

Data Type / Min - Max Values

LodgingItemType

Lodging extra charge type :
G = Gift Shop
L = Laundry
B = Mini bar
R = Restaurant
T = Telephone

1

LodgingItemAmount

Amount for lodging extra charge item. Implied decimal.

8

RentalExtraChargeItem

Property

Description

Data Type / Min - Max Values

RentalExtraChargeItemType

Car rental extra charge type:
M = Extra Mileage
S = Gas
N = Late Return
W = One-Way Service
P = Parking Violation

1

RentalExtraChargeTypeAmount

Amount for car rental extra charge item. Implied decimal.

8

Output

The following table contains descriptions for the PaymentResponse output object properties.

Note: You should only look at the results in the PaymentResponse

Property

Description

Data Type / Min - Max Values

AuthCode

Transaction authorization code from the payment processor. This value is an approval code for approved transactions or an error code/message for declined transactions.

String;
Max Value = 15

ApprovedAmount

The actual amount approved by host. This may differ from the requested amount.

String;
Max Value = 15

AvsResponse

AVS response. See AVS Response Codes(3.1.6 Examples) for a list of possible responses.

String;
Max Value = 10

BogusAccountNumber

Partially masked card number. The first 6 and last 4 digits of the card number are present with zeros in between. This card number will not pass the mod 10 check.

String;
Max Value = 20

CardType

Displays the card type (determined by BIN range).

List of items:

Visa, Mastercard, Discover, Amex, Diners, JCB, CUP (China Union Pay), Bank, None

String;
Max Value = 20

CardModifier

Displays the featured function submitted in addition to the tender type used to process a transaction.

List of items:

Business, FSA, Commercial, FoodStamp, Check, Savings, Cash, None

String;
Max Value = 10

CardClass

Displays the tender type used to process a transaction.

List of items:

Credit, Debit, Gift, Prepaid, EBT, Fleet, None

String;
Max Value = 10

CvResponse

The CV response code. See CV Response Codes on pages 38 for a list of possible responses.

String;
Max Value = 10

RefNum

Gateway reference/PnRef number. Used for follow‐on transactions (i.e., Void, Reversal).

String;
Max Value = 15

RemainingBalance

Remaining balance on gift or prepaid card.

String;
Max Value = 15

RequestedAmount

Original requested amount of the transaction.

String;
Max Value = 15

ResultCode

Result code of the transaction. See on page 35 for more information.

String;
Max Value = 10

ResultTxt

Details from the processor or payment gateway about the transaction result.

String;
Max Value = 15

Timestamp

Time and date of the transaction.

String;
Max Value = 30

ExpirationDate

Echo back of the expiration date.

String;
Max Value = 4

GatewayMessage

Message from the gateway.

String;
Max Value = 30

InternalMessage

Detailed information provided by the gateway / processor regarding results of the transaction request.

String;
Max Value = 50

AVSMessage

Unipay AVS Match Result Message.

String;
Max Value = 10

CVMessage

Unipay CVV/CVV2 Match Result Message.

String;
Max Value = 10

IsoCountryCode

Country code from the gateway.

String;
Max Value = 10

IsoRequestDate

Requested date from the gateway.

String;
Max Value = 10

NetworkReferenceNumber

Gateway Network reference number.

String;
Max Value = 15

MerchantCategoryCode

Merchant Category Code from the gateway.

N/A

NetworkMerchantId

Merchant id from the gateway.

N/A

NetworkTerminalId

Network terminal id from the gateway.

N/A

ResponseTypeDescription

 

N/A

StreetMatchMessage

 

N/A

ExtData

Returns extra data for the extended data fields submitted in the processed transaction (multiple field information may be returned in XML format).

N/A

Token

Represents the tokenized card number received from a token request or authorization.

String;
Max Value = 22

Memo

Conditional. Present if user previously supplied data.

String;
Max Value = 60

ServiceFeeResult

Returns result for Service Fee transactions. Data may be populated in multiple fields and returned in XML format.

String; XML

EntryMode

Returns back the card entry method: Swipe, EMV, Tap.

String;

WalletID

Returns the wallet ID. 

String;
Max Value = 36

WalletPaymentMethodID

Returns the wallet payment method ID.

String;
Max Value = 36

WalletResponseMessage

Returns the wallet response message.

String;
Max Value = 100

WalletResponseCode

Returns the wallet response code. 

String;
Max Value = 2

Table of Contents

Table of Contents