PayGuardian Android SDK

Owned by Jose Bueno
Last updated: Dec 12, 2024 by Noah Hippensteel
20 min read

SDK Download:

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.

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

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)

  • 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.

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)

// 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 Android 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)

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

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.

public interface PayGuardianDelegate { void initiateTransaction(PaymentRequest request); void onTransactionStateChanged(TransactionState transactionState, String message); void onReaderStateChanged(ReaderState readerState, String message); void onMessageReceived(String message); void onResponseReceived(PaymentResponse paymentResponse); void onError(ArrayList<String> errors); }

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.

While testing with the ID Tech VP3300, we found it helpful to leave it plugged into USB power. 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 those requests to the wired device regardless of the source.

 

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.

 

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 = 50

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

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.

String;
Min Value = 1;
Max Value = 25

CardNumber

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

String;
Min Value = 1;
Max Value = 19

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 =

HostingSoftware

Optional.

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.

Int

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.

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 = 15

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.

ServiceFee

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

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 = 1

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.

String;
Min Value = 4;
Max Value = 9

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.

String;
Min Value = 4;
Max Value = 9

Implied Decimal

ClinicAmt

The portion of the Healthcare Amount spent on hospitalization. Processed as implied decimal. $1.25 would be represented as 125.

String;
Min Value = 4;
Max Value = 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 = 12

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.

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

 

Property of BridgePay Network Solution ©2024