PayGuardian Android SDK

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

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.

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 =

DisableEMV

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

TBD

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

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.

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

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

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

CustomFields

Reserved for future use. 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: RequestHandler Service

URL String

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