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:
The mPOS system collects order information and determines that the customer will pay with one of the supported tender types.
The mPOS system invokes the PayGuardian app method.
The PayGuardian payment screen loads and prompts the user to swipe or insert card.
After collecting all transaction information, PayGuardian transmits the data to the server.
After receiving a response from the host, the payment screen returns to processing results back to the mPOS system.
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: ***UNKNOWN is currently only supported for use with the Ingenico devices. | String; |
TransType | Required. Valid values are: | String; |
TransIndustryType | Optional. Valid values are: | String; |
Amount | Required. Total transaction amount (includes subtotal, cash back, tax, and tip (Format example: 0000.00) | String; |
Username | Required. Username of the Merchant | String; |
Password | Required. Password of the Merchant. | String; |
Street | Optional. Zip code of billing address. | String; |
OrigRefNum | Original reference number. Used for follow‐on transactions (e.g., Void, Reversal). | String; |
Country |
| String; |
Phone |
| String; |
| N/A | |
MerchantCode | Required. BridgePay Merchant Code. | String; |
MerchantAccountCode | Required. BridgePay Merchant Account Code. | String; |
InvNum | Required. POS system invoice/tracking number. | String; |
ReferenceID | Optional. Can be populated to echo back a variable in the response message. | String; |
TerminalType | Required. Terminal device type to be used for transaction processing. Valid values are (case-sensitive): | String; |
PartialAuthorization | Optional. Sets the partial authorization flag for a transaction. The default setting is ‘false’ (meaning not active). | String; |
BankAccountNum | Optional. The bank account number for ACH and Check transactions. | String; |
RoutingNum | Optional. The routing number for ACH and Check transactions. Can contain up to 10 numbers. | String; |
HolderType | Optional. Single character, either P (Personal account) or O (Organization account). | String; |
CardholderName | Optional. Name as it appears on the credit card, debit card, or gift card. | String; |
CardNumber | Optional. Account number of a credit card, debit card, or gift card used when collecting card data outside of PayGuardian (not recommended). | String; |
ExpDate | Optional. Expiration date of a credit card, debit card, or gift card (required for Token transactions). | String; |
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; |
Memo | Optional. User supplied data. Valid values are: alphanumeric, dashes, spaces, and periods. | String; |
SoftwareVendor | Optional. Name of vendor that developed the software used in transmitting the transaction. | String; |
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; |
VoiceAuthCode | Optional. Authorization Code for Voice Authorizations only when authorization was achieved outside of the network (by phone or other means). | String; |
TaxRate | Optional. Processed as implied decimal. 5.5% would be represented as 550. Additional Tax Amount. REQUIRED FOR LEVEL II/III | String; |
TaxAmount | Optional. Processed as implied decimal. $1.25 would be represented as 125. REQUIRED FOR LEVEL II. | String; |
TaxIndicator | Optional. Valid values are: P (Provided), N (Not Provided), or E (Exempt). REQUIRED FOR LEVEL II/III. | String; |
ShipToName | Optional. Shipping address name. REQUIRED FOR LEVEL II/III. | String; |
ShipToStreet | Optional. Shipping address street. REQUIRED FOR LEVEL II/III. | String; |
ShipToCity | Optional. Shipping address city. REQUIRED FOR LEVEL II/III. | String; |
ShipToState | Optional. Shipping address state. REQUIRED FOR LEVEL II/III. | String; |
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; |
ShipToCountryCode | Optional. Shipping address country code. REQUIRED FOR LEVEL II/III. ISO 3166-1 alpha-2 codes. | String; |
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; |
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 |
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 |
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 |
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 |
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 |
LocalTaxIndicator | Availability pending processor certification. Conditional. *** REQUIRED FOR LEVEL III*** P (Provided), N (Not Provided), or E (Exempt). | String |
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 |
NationalTaxIndicator | Availability pending processor certification. Conditional. *** REQUIRED FOR LEVEL III*** P (Provided), N (Not Provided), or E (Exempt). | String |
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 |
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 |
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 |
CustomerAccountTaxID | Availability pending processor certification. Conditional. *** REQUIRED FOR LEVEL III*** VAT registration number of the customer responsible for this transaction. | String |
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> | Collection |
ItemCode | Availability pending processor certification. Conditional - Required when included in "Item" collection. Unique identifier assigned to this item in the submitter’s inventory system. | String |
ItemCommodityCode | Availability pending processor certification. Conditional - Required when included in "Item" collection. Acquirer designated standardized code that classifies this item. | String |
ItemDescription | Availability pending processor certification. Conditional - Required when included in "Item" collection. Short description of the item. | String |
ItemQuantity | Availability pending processor certification. Conditional - Required when included in "Item" collection. Quantity of item units purchased as part of this transaction. Up to 4 decimal places. | Decimal |
ItemUnitCostAmt | Availability pending processor certification. Conditional - Required when included in "Item" collection. Processed as implied decimal. $1.25 would be represented as 125. Cost of a single unit of the item. | Integer |
ItemUnitMeasure | Availability pending processor certification. Conditional - Required when included in "Item" collection. Unit of measure used to quantify the items purchased/refunded (e.g. kg, lb., inch). | String |
ItemTaxRate | Availability pending processor certification. Conditional - Required when included in "Item" collection. Processed as implied decimal. 5.5% would be represented as 550. Rate of the tax (if any) charged on this item. | String |
ItemTaxAmount | Availability pending processor certification. Conditional - Required when included in "Item" collection. Processed as implied decimal. $1.25 would be represented as 125. Amount of tax charged for this item. | Integer |
ItemTaxIndicator | Availability pending processor certification. Conditional - Required when included in "Item" collection. P (Provided), N (Not provided), or E (Exempt). | String |
ItemTaxCode | Availability pending processor certification. Conditional - Required when included in "Item" collection. Acquirer designated value classifying the tax that was charged for this item. | String |
ItemDiscountRate | Availability pending processor certification. Conditional - Required when included in "Item" collection. Processed as implied decimal. 5.5% would be represented as 550. Rate of discount (if any) that was applied to this item. | Integer |
ItemDiscountAmount | Availability pending processor certification. Conditional - Required when included in "Item" collection. Processed as implied decimal. $1.25 would be represented as 125. Amount of tax charged for this item. | Integer |
ItemTotalAmount | Availability pending processor certification. Conditional - Required when included in "Item" collection. Processed as implied decimal. $1.25 would be represented as 125. Amount of tax charged for this item. | Integer |
ItemIsCredit | Availability pending processor certification. Conditional - Required when included in "Item" collection. True = T (Item is being returned), F = False (Default if not passed - Item is being purchased). | String |
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; |
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; |
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; |
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: | X |
ServiceUser | User name of the Service Fee Merchant Account. | String; |
ServicePassword | Password of the ServiceUser. | String; |
ResellerCode | Reseller ID assigned by the gateway for the Reseller of the Service Fee account. | String; |
MerchantCode | Merchant ID assigned by the gateway for the Merchant of the Service Fee. | String; |
MerchantAccountCode | Merchant Account ID assigned by the gateway for the Merchant Account of the Service Fee. | String; |
CardNotPresent | Optional. When set to ‘TRUE’, the transaction is treated as a Card Not Present transaction. Valid values are: TRUE = Card Not Present | Boolean |
ForceOnDuplicate | Optional. Can force a duplicate transaction to process when set to true. Valid values are: TRUE = Force duplicate transaction to process | 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) | Boolean |
ConfigureVivopay | Optional. Push config file settings to device (one-time setup). True = push config file | 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; |
Wallet | Optional. The ability to create a wallet within processing a request by setting: <Wallet>new</Wallet> | NSString; |
SettlementDelay | Optional. The period for which a Sale-Auth transaction settlement is delayed. | String; |
CustomFields | Optional. The ability to pass custom user defined fields to the gateway via a XML string. | NSString; |
CustomFields | Reserved for future use. Availability pending processor certification. Optional. Valid Values are: CUSTOMER UNSCHEDULED RECURRING or INSTALLMENT | String; |
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; |
ApprovedAmount | The actual amount approved by host. This may differ from the requested amount. | String; |
AvsResponse | AVS response. See AVS Response Codes(3.1.6 Examples) for a list of possible responses. | String; |
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; |
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; |
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; |
CardClass | Displays the tender type used to process a transaction. List of items: Credit, Debit, Gift, Prepaid, EBT, Fleet, None | String; |
CvResponse | The CV response code. See CV Response Codes on pages 38 for a list of possible responses. | String; |
RefNum | Gateway reference/PnRef number. Used for follow‐on transactions (i.e., Void, Reversal). | String; |
RemainingBalance | Remaining balance on gift or prepaid card. | String; |
RequestedAmount | Original requested amount of the transaction. | String; |
ResultCode | Result code of the transaction. See on page 35 for more information. | String; |
ResultTxt | Details from the processor or payment gateway about the transaction result. | String; |
Timestamp | Time and date of the transaction. | String; |
ExpirationDate | Echo back of the expiration date. | String; |
GatewayMessage | Message from the gateway. | String; |
InternalMessage | Detailed information provided by the gateway / processor regarding results of the transaction request. | String; |
AVSMessage | Unipay AVS Match Result Message. | String; |
CVMessage | Unipay CVV/CVV2 Match Result Message. | String; |
IsoCountryCode | Country code from the gateway. | String; |
IsoRequestDate | Requested date from the gateway. | String; |
NetworkReferenceNumber | Gateway Network reference number. | String; |
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; |
Memo | Conditional. Present if user previously supplied data. | String; |
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; |
WalletPaymentMethodID | Returns the wallet payment method ID. | String; |
WalletResponseMessage | Returns the wallet response message. | String; |
WalletResponseCode | Returns the wallet response code. | String; |
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.
Table of Contents
- 1 Introduction
- 2 PayGuardian Setup
- 3 Integration Process
- 4 PayGuardian Integration
- 5 PayGuardian Library (SDK) Integration
- 5.1 SDK Integration Code Example
- 5.2 Program Input Object
- 5.3 Program Output Object
- 5.4 PayGuardian Android XML Data Format
- 5.4.1 Examples
- 5.4.1.1 MSR Sale Type Request
- 5.4.1.2 MSR Sale Type Response
- 5.4.1.3 MSR Sale Receipt
- 5.4.1.4 Sale_Auth Transaction Type Request
- 5.4.1.5 Sale_Auth Transaction Type Response
- 5.4.1.6 Sale_Auth Receipt
- 5.4.1 Examples
Property of BridgePay Network Solution ©2024