PayGuardian Android SDK

This material is currently unsupported pending SDK updates and should not be used for new integrations. Please contact Integration Support for details.

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 to the Payments Card Industry Data Security Standards (PCI DSS) compliance requirements. 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 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.

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.


PayGuardian Setup

Requirements

Operating Systems

PayGuardian has a PA‐DSS certification for the following operating systems:
Android SDK version 22 (LollyPop 5.1) and above
Android device should have the USB host feature, Audio Jack, or Bluetooth connection
Ingenico card reader device - RBA version 15.0.4 (RBA version 23.0.2 needed for EMV)
BBPOS device Chipper 2 or WisePad 2 - terminal software
ID TECH device Vivopay 3300 (formerly known as Unipay III) - terminal software NEO v1.01.129

Android Application Setup Guide

Minimum Requirements

  • Android SDK version 22 (LollyPop 5.1) and above

  • Android device should have the USB host feature, Audio Jack, or Bluetooth connection

  • Ingenico card reader device - RBA version 15.0.4 (RBA version 23.0.2 needed for EMV)

  • BBPOS device Chipper 2 or WisePad 2 - terminal software

  • ID TECH device Vivopay 3300 (formerly known as Unipay III) - terminal software NEO v1.01.129

Setup

Install the PayGuardian application into the device.

App Store: TBD

Manual Setup

Install the application onto the device.

Step1: Copy the PayGuardian APK file to the Android device

 The APK file must be requested from BridgePay Integrations Support. All integrators are advised to request a test account via this portal. 

Step2: Go to ‘Settings’, scroll down to ‘Security’, and select ‘Unknown sources’. Selecting this option allows the app installation to occur outside of the Google Play store. Some devices permit the selection of the option to be warned before installing harmful applications. This feature can be enabled by selecting the ‘Verify applications’ option in the Security settings.

Step3: Click the Apk file to install the application.

 PayGuardian Android supports Portrait and Landscape orientation. 

Change Processing Mode

The PayGuardian Android application has Test, Production, and Development modes that can be switched as needed. The Test mode setting should always be used for integration and test purposes.

PayGuardian Android offers three methods of switching the gateway URL between Production, Test, and Development modes, either through an integration or via the PayGuardian Android application.

PayGuardian Android Application - Integrated Processing Mode Switch

PayGuardian Android allows integrators to remotely change the gateway URL between the production, test, and development environments. An integer is sent via an intent where

0 = TEST, 1 = PRODUCTION, and 2 = DEV.

To accomplish this, use the following example:

Intent setModeIntent = new Intent(); setModeIntent.putExtra("Mode",0); setModeIntent.setComponent(new ComponentName("com.bpn.payguardian", "com.bpn.payguardian.service.ChangeModeService")); startService(setModeIntent);

This will execute the remote IntentService and set the gateway URL accordingly without interrupting the mPOS application.

PayGuardian Android Application - Manual Processing Mode Switch

Step1: On the main PayGuardian App screen, press the Menu button located in the upper right hand corner of the screen (see mainScreen.PNG).

Step2: Select the Mode item (Menu.PNG

Step3: The current processing mode will be highlighted in the list display. Select the new processing mode option and press the Done button (see setMode.PNG) to save the changes. If no changes were made, close the menu. The current selected processing mode will remain unchanged.


Android Library (SDK) Setup Guide

Minimum Requirements

  • Android SDK version 22 (LollyPop 5.1) and above

  • Android device should have the USB host feature, Audio Jack, or Bluetooth connection

  • Ingenico card reader device - RBA version 15.0.4 (RBA version 23.0.2 needed for EMV)

  • BBPOS device Chipper 2 or WisePad 2 - terminal software

  • ID TECH device Vivopay 3300 (formerly known as Unipay III) - terminal software NEO v1.01.129

AAR Setup

 The instructions below are based on the assumption that Android Studio 1.32 or later will be used in the development environment. The directions will differ for alternate development environments and can be obtained by contacting Developer Support.  

Step 1: Copy the payguardianandroid-release.aar file to your project’s /libs folder.

Step 2: Add the KSoap maven url to your build script “https://oss.sonatype.org/content/repositories/ksoap2-android-releases/

Step 3: Add the maven package “com.google.code.ksoap2-android:ksoap2-android:3.6.2” to your build script.

Step 4: Add the maven package “org.simpleframework:simple-xml:2.7.+” to your build script.

Step 5: Exclude the following from simple-xml in your build script: stax, stax-api, and xpp3

Step 6: Select "New Module" option under the File menu.

Step 7: Select "Import .JAR/.AAR Package" and click next.

Step 8: Select the path to the payguardianandroid-release.aar file and click Finish.

Step 9: Select “Project Settings” under the File menu.

Step 10: Under “Modules”, in the left menu, select “app”.

Step 11: Click the “Dependencies” tab.

Step 12: Click the green “+” symbol in the upper right corner.

Step 13: Select “Module Dependency”.

Step 14: Select the new PayGuardian module from the list display.

Note: The dependencies packaged in the standard PayGuardianandroid-release.aar file are:    

  • RBA_SDK.jar (SDK version 5.5.9)

  • emvparser-1.0.0.jar

  • Universal_SDK_1.00.126.jar

  • Android_Platform_Adapter.jar

  • wisepadapi-android-2.7.0.jar

  • emvswipeapi-android-2.12.3.jar

Android Device Configuration

Android device and card reader should be connected through either USB Host connectivity, Audio Jack, or Bluetooth pairing options. 

Ingenico

USB Supported devices: iPP350 and iPP320

The Android device and card reader should be connected through the USB Host connection via the OTG (On the Go) cable.

Bluetooth Supported devices: iCMP, and iSMP

The Android device and card reader should be paired through the Bluetooth connection.

BBPOS

Audio Jack Supported devices: Chipper 2
The Android device and card reader should be connected through the audio jack.
Bluetooth Supported devices: WisePad 2, WisePOS, WisePOS Manual, Chipper 2 Bluetooth
The Android device and card reader should be paired through the Bluetooth connection.

ID TECH

Audio Jack Supported devices: VP3300 (formerly Unipay III)

The Android device and card reader should be connected through the audio jack. (If using Android version 6.0 or later, microphone permission must be enabled for the PayGuardian application. To do this go into Settings -> Apps -> PayGuardian -> Permisssions -> Enable microphone)

USB Supported devices: Minismart II and VP3300 USB

The Android device and card reader should be connected through the USB Host connection via the OTG (On the Go) cable.

Bluetooth Supported devices: Minismart II and VP3300

The Android device and card reader should be paired through the Bluetooth connection. 

The ID TECH Firmware Upgrade Tool article references the current firmware versions and process to upgrade your VP3300 device.

Magtek

Audio Jack Supported devices: eDynamo 

Innowi

Supported devices: ChecOut M

Setup: The Innowi device is an all-in-one point of sale and payment processing solution that does not have an external connection setting. Instead, both your POS and the PayGuardian Android Library must be installed onto the Innowi device directly. This can be accomplished by loading your POS.apk file with the bundled PayGuardian Android Library used in your integration via:

  • USB Host connection using the OTG (On the Go) cable - download both your POS.apk files with the bundled PayGuardian Android Library.

  • App Store - download your POS.apk files with the bundled PayGuardian Android :ibrary directly from the App store. 


Integration Process

Getting Started

The PayGuardian application should be installed in the Android device prior to the start of an integration.

Contact: Integration Support to receive the developer application build of PayGuardian Android. The developer application build points to the PayGuardian UAT environment for integration and certification testing.

Integration Options

PayGuardian Android currently offers several integration options:App-to-App communication, Custom URI, or direct to Library (SDK).Please note that the enumerations, properties and methods contained within this document are only for a PayGuardian Android integration.

 Remember that the application integrating to PayGuardian Android should never touch, collect, transmit, or store the account holder’s actual card information.  
 The integrating application must always pass a unique identifier for each mPOS user or cashier. 

Transaction Flow Summary

The following list summarizes the steps involved in processing a transaction:

  1. The mPOS system collects order information and determines that the customer will pay with one of the supported tender types.

  2. The mPOS system invokes the PayGuardian app method. 

  3. The PayGuardian payment screen loads and prompts the user to swipe or insert card.

  4. After collecting all transaction information, PayGuardian transmits the data to the server.

  5. After receiving a response from the host, the payment screen returns to processing results back to the mPOS system. 

  6. The mPOS system analyses the response data. 


PayGuardian Integration

Integration Methods

By using App to App communication or Custom URI integration methods, PayGuardian Android ensures that your application remains completely out of scope of the Payment Application Data Security Standard (PA‐DSS) certification requirement. When a transaction is initialized, the PayGuardian Android application will place itself in the foreground while the request is being processed. Conversely, when the response is returned, it is transmitted back to the requesting application which is then placed into the foreground.

App-to-App Communication Method

The PayGuardian Android application is accessed by starting an activity with an intent which encapsulates a request payload.
Note* Where paymentRequestXml is a String representation of the Program Input Object (currently) in section 3.1.4

{ final ActivityInfo activity = app.activityInfo; final ComponentName name = new ComponentName(activity.applicationInfo.packageName, activity.name); sendIntent.setComponent(name); startActivityForResult(sendIntent, PAYGUARDIAN_REQUEST_CODE); break; } }

Custom URI Method

The custom URI integration method can be used from both native android apps and non-native apps (such as a web application). There is an additional required field for the Custom URI integration method named “callbackUri”. This is the URI (associated with your application) where PayGuardian will post the payment response.

If the request originated from a native app intent, the response will be returned via an Intent with the data field containing the callbackUri, and with the response XML serialized in the PaymentResponse element of the query string.

If the request originated from a non-native app, the response will be returned to a web browser via a BrowserIntent using the callbackUri provided. The request is a String representation of the Program Input Object XML and must have no new lines, line feeds, or whitespace between elements. The request must be URL encoded.

The custom URI must match the format:

bpn://bridgepaynetwork.com/transact?PaymentRequest=ProgramInputObjectXML

A ProgramInputObjectXML example is:

%3CPaymentRequest%3E%3CTenderType%3ECREDIT%3C%2FTenderType%3E%3CTransType%3ESALE%3C%2FTransType%3E%3CAmount%3E5.00%3C%2FAmount%3E%3CUsername%3EMerchantUser%3C%2FUsername%3E%3CPassword%3EMerchantPass%3C%2FPassword%3E%3CZip%2F%3E%3CStreet%2F%3E%3COrigRefNum%2F%3E%3CCountry%2F%3E%3CPhone%2F%3E%3CEmail%2F%3E%3CMerchantCode%3EMerchantCode%3C%2FMerchantCode%3E%3CMerchantAccountCode%3EMerchantAccountCode%3C%2FMerchantAccountCode%3E%3CInvNum%3E1234%3C%2FInvNum%3E%3CCallbackUri%3Eyour%3A%2F%2Fcustom%2Furi%3C%2FCallbackUri%3E%3CReferenceID%3E555%3C%2FReferenceID%3E%3CTerminalType%3Ekeyed%3C%2FTerminalType%3E%3C%2FPaymentRequest%3E

This string, again, is a URL encoded representation of the Program Input Object XML detailed in section #####. An unencoded version of this string, for reference, looks like:

Example of sending custom URI via native-app Intent:


PayGuardian Library (SDK) Integration

The PayGuardian Android SDK gives you direct access to the PayGuardian API directly within your application without the need to call an activity of a separate application. The SDK provides a simple convenience class aptly named PayGuardian, that makes a simple integration easy.

The PayGuardian class constructor is:

public PayGuardian(Context context, PayGuardianCallback callback)

The constructor has 2 arguments of the types: android.content.Context (the calling application context) and PayGuardianCallback. PayGuardianCallback is an interface that is implemented by the calling application to receive notifications on status, results, or errors from the PayGuardian SDK.

The PayGuardianCallback has 2 methods:

void statusUpdated(PayGuardianStatus status);

void transactionResponse(PaymentResponse response);

PayGuardianStatus is an enumeration of different status events, so that the calling application can update its UI or other items, as the status of a transaction changes.

PaymentResponse is the Program Output Object detailed in section 3.1.5

The PayGuardian class contains one method to initialize a transaction:

public boolean processTransaction(PaymentRequest request, String processingMode)

The “processTransaction” method is non-blocking and will return a Boolean value indicating a success, or failure, of initializing a transaction. This method will only return false in the event that there is an unrecoverable exception (NullPointerException) during initialization. There are two arguments to the method. First, the PaymentRequest object (detailed in section 3.1.4 Program Input Object). Second, the test mode flag that will tell PayGuardian whether or not this is a live transaction.

As a transaction navigates through various steps (communicating with the terminal, configuring terminal, communicating with the gateway, etc.), the “statusUpdated” callback method will be called with the status change information.

When a transaction completes (either success or error), the transactionResponse callback method will be called with the PaymentResponse object. In the case of an error, the error code and message will be available in the response object as detailed in section 3.1.5

SDK Integration Code Example

The After the transaction is started, it can only be cancelled by calling the payGuardian.cancelTransaction() method.

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

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), = 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: 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.

MSR Sale Type Response

An example of a basic MSR sale transaction response.

MSR Sale Receipt

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

Sale_Auth Transaction Type Request

An example of a basic authorization only transaction request.

Sale_Auth Transaction Type Response

An example of a basic authorization only transaction response.

Sale_Auth Receipt

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

 

 

Property of BridgePay Network Solution ©2024