PayGuardian iOS SDK

Owned by Mark Mauer, created
Last updated: Jan 31, 2024
28 min read

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 iOS is a light weight, highly secure iOS framework library that integrates seamlessly into mPOS applications. PayGuardian iOS 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 iOS 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 a BPNPaymentRequest object and passes it to a new instance of the PayGuardianTransaction object.
PayGuardian obtains the card information via the claiming of the mPOS device using the Bluetooth API (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

Requirement

Operating Systems
PayGuardian has a PA‐DSS certification for the following operating systems:

iOS Version 14.0 and above

iOS Application Setup Guide

Minimum Requirements

  • iPad/iPhone device with iOS 13.0 and above

Project Dependencies

To integrate to BridgePay's PayGuardian iOS, please review the following. The required mPOS application executable files are located in PayGuardian iOS Framework. Always be sure to reference the Certified Device matrix to ensure your device is listed. 

PayGuardian iOS SDK

Test Application (For use in TestFlight)

PayGuardian ​iOS Release Notes

Certified Devices

ID TECH Upgrade Tool

Project Setup

Add the following bundled dependencies to the Linked Libraries and Frameworks section of the Xcode project within the mPOS application.

  • PayGuardian_SDK.framework - Embed & Sign

  • Ono.framework - Embed & Sign

  • IDTECH.xcframework - Do Not Embed

Add the following bundled dependency to the Embedded Binaries section within the mPOS application.

  • Ono.framework

  • PayGuardian_SDK.framework

Add the following standard iOS frameworks to the Linked Libraries and Frameworks within the mPOS application.

  • CFNetwork.framework

  • CoreAudioKit.framework

  • CoreAudio.framework

  • AudioToolbox.framework

  • MediaPlayer.framework

  • MessageUI.framework

  • AVFoundation.framework

  • ExternalAccessory.framework

  • CoreTelephony.framework

  • CoreBluetooth.framework

  • UIKit.framework

  • Foundation.framework

  • CoreGraphics.framework

  • libxml2.tbd

The bundled framework files are located in the ‘Dist’ folder of the PayGuardian_SDK project.

 

info.plist Configuration

You must add a ‘Privacy - Bluetooth Always Usage Description’ to this file in order to enable the permissions checker to handle obtaining permission.

Device Configuration

ID TECH

VP3300 (formerly Unipay III) 

The VP3300 is a Bluetooth Low Energy device that can be paired by passing in a known friendly name into the TerminalCommConfig object or else having the controller scan for and return all unpaired devices in range. When pairing, the friendly name is used only to identify the device to the CoreBluetooth manager. The NSUUID that is generated represents the connection between the host device and the reader and should be stored in your application. This NSUUID is not transferrable to other devices.

Note on bleFriendlyName: the documented behavior of this device is that it will first search for a device matching the friendly name if provided but will connect to the first unpaired device in range if it is not found. For this reason we suggest passing in an empty string or nil.

Device Registration

The example below sets up a transaction object for scanning nearby unpaired VP3300 devices. Once the device is done scanning, it returns an array of device friendly names which can then be used to pair the desired reader. The friendly name gets passed into the transaction object via connectWithFriendlyName; a successful connection will return the UUID representing the pairing between that device and reader.

- (void) scanForDevices { _transaction = [[PayGuardianTransaction alloc] initAndScanForDevices: TERMINAL_TYPE_IDTECH_UNIPAY_BT onReaderStateChanged: ^(PayGuardianReaderState readerState) { dispatch_async(dispatch_get_main_queue(), ^(void){ switch(readerState) { case Connected: // Store the UUID so registration does not need to occur again unless // unpairing occurs. self->_registeredUUID = [self->_transaction getConnectedDeviceIdentifier]; [self appendToLogMessages:[NSString stringWithFormat:@"%@", self->_registeredUUID]]; [self->_prefs setObject:[NSString stringWithFormat:@"%@", self->_registeredUUID] forKey:UUID_KEY]; break; case ScanComplete: self->_foundBleNames = self->_transaction.getFoundDeviceNames; if (self->_foundBleNames != nil && self->_foundBleNames.count > 0) { for (NSString* name in self->_foundBleNames) { [self appendToLogMessages:[NSString stringWithFormat:@"Found %@", name]]; } [self presentAvailableDevicesPicker]; } else { [self appendToLogMessages:@"No devices located"]; } break; default: break; } }); }]; } - (void) presentAvailableDevicesPicker { UIAlertController *alert = [UIAlertController alertControllerWithTitle:@"Available devices" message:@"" preferredStyle:UIAlertControllerStyleActionSheet]; for (NSString* name in _foundBleNames) { UIAlertAction* a = [UIAlertAction actionWithTitle:name style:UIAlertActionStyleDefault handler:^(UIAlertAction* action) { [self->_transaction connectWithFriendlyName:name]; }]; [alert addAction:a]; } // This is needed to anchor the popover on iPad implementations UIPopoverPresentationController *popPresenter = [alert popoverPresentationController]; popPresenter.sourceView = __logMessages; popPresenter.sourceRect = __logMessages.bounds; [self presentViewController:alert animated:YES completion:^(){ self->_foundBleNames = nil; }]; }
Device Registration - legacy

This block is an example of using the pre-iOS 9 BLE scanning method. Using this method will generate a First Responder error on any project that uses a SceneDelegate and should not be used for new development.

- (void) vp3300Registration { _transaction = [[PayGuardianTransaction alloc] initForRegistration:TERMINAL_TYPE_IDTECH_UNIPAY_BT bleFriendlyName:@"" onReaderStateChanged:^(PayGuardianReaderState readerState) { dispatch_async(dispatch_get_main_queue(), ^(void){ switch(readerState) { case Connected: NSLog(@"Card reader status is connected"); NSLog(@"%@", [[_transaction getConnectedDeviceIdentifier] UUIDString]); [[self bleUUID] setText:[[_transaction getConnectedDeviceIdentifier] UUIDString]]; break; default: } }];

 

Transaction with TerminalCommConfig

terminalCommConfig.terminalType = TERMINAL_TYPE_IDTECH_UNIPAY_BT; terminalCommConfig.disableEmv = false; terminalCommConfig.enableContactless = true; terminalCommConfig.useQuickChip = true; terminalCommConfig.bleDeviceUUID = {{stored uuid}}; BPNPaymentRequest *request = [[BPNPaymentRequest alloc] init:terminalCommConfig username:_username password:_password merchantCode:_mc merchantAccountCode:_mac tenderType:TENDER_TYPE_CREDIT industryType:TRANSACTION_INDUSTRY_TYPE_RETAIL invoiceNumber:[self newInvoiceNum] amount:[NSDecimalNumber decimalNumberWithString:amt] tipAmount:nil cashBackAmount:nil testMode:TRUE]; transaction = [[PayGuardianTransaction alloc] initWithPaymentRequest:request]; [transaction runOnCompletion: ^(BPNPayment *payment, NSError *error) { } onStateChanged: ^(PayGuardianTransactionState state) { } onReaderStateChanged:^(PayGuardianReaderState readerState) { } onCardDataAvailable:^(NSString *cardIdentifier) { // you must call resumeCardRead or cancel on the transaction object //to continue processing the transaction when this block is implemented. [transaction resumeCardRead]; }];

Integration Process

Getting Started

The PayGuardian iOS Framework files must be added to the XCode project prior to the start of an integration.

Contact: A test or live merchant account with BridgePay is necessary to successfully process transactions. To acquire a test account and receive the developer application build of the PayGuardian iOS Framework library, complete the Test Account Request form.

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 iOS Framework library.

  3. The payment screen loads and prompts the user to enter customer and payment data.

  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 the processing results back to the mPOS system.

  6. The mPOS system analyses response data. 

PayGuardian Integration

BPNPaymentRequest

The BPNPaymentRequest object contains the following properties that can be accessed or modified via getter and setter methods: 

Property

Description

Data Type / Min - Max Values

Property

Description

Data Type / Min - Max Values

Amount

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

NSDecimalNumber
Min = 4;
Max = 12

TipAmount

The tip amount. The tip is not added into the total amount, it is an in-addition-to the specified amount.
(Format example: DDDD. CC)

NSDecimalNumber
Min = 4;
Max = 12

InvoiceNumber

Required. POS system invoice/tracking number. (Alpha/Numeric characters only)

NSString
Min = 1;
Max = 12

TenderType

Required. Valid values are: TENDER_TYPE_CREDIT,
TENDER_TYPE_DEBIT,
TENDER_TYPE_GIFT,
TENDER_TYPE_LOYALTY,
TENDER_TYPE_EBT_CASH,
TENDER_TYPE_EBT_FOOD,
TENDER_TYPE_BANK_ACCOUNT_CHECKING, TENDER_TYPE_BANK_ACCOUNT_SAVINGS, TENDER_TYPE_SIGNATURE

NSString;
Constant

TransactionType

Required. Valid values are:
TRANSACTION_TYPE_SALE: Makes a purchase with a
credit card, debit card, gift card, or loyalty card. TRANSACTION_TYPE_SALE_AUTH: (Authorization 
only) Verifies/authorizes a payment amount on a credit card.
TRANSACTION_TYPE_REFUND: Returns a credit card or debit card payment.
TRANSACTION_TYPE_VOID: Removes a credit card transaction from an unsettled batch. 
TRANSACTION_TYPE_CAPTURE: Places a
‘TRANSACTION_TYPE_SALE_AUTH’ transaction into the open credit batch for settlement. Requires the 
Original Reference Number and updated Amount.
TRANSACTION_TYPE_TIP_ADJUST: Modifies
previously authorized ‘TRANSACTION_TYPE_SALE’
transaction to include a TipAmount and updates the transaction total amount. Requires the Original Reference Number. Can only be used on an unsettled transaction.
TRANSACTION_TYPE_CREDIT: Blind return transaction for a credit card, debit card, or giftcard 
without using a previous reference number. TRANSACTION_TYPE_BALANCE_INQUIRY: Performs
an inquiry for the remaining card balance against a gift
card.
TRANSACTION_TYPE_FIND_TRANSACTION: Retrieves
a previous transaction using the Original Reference Number or the Transaction Code. 
TRANSACTION_TYPE_ACTIVATE: Performs an activation and sets the initial balance of a new gift card.
TRANSACTION_TYPE_REACTIVATE: Adds funds to an existing balance of an active gift card. 
TRANSACTION_TYPE_DEACTIVATE: Permanently terminates an active gift card. 
TRANSACTION_TYPE_PCI_TOKEN: Used to send a
request for a secure PCI token.
TRANSACTION_TYPE_ACCOUNT_VERIFICATION: Used to verify a credit card is valid.
 

NSString;
Constant – valid values are listed.

Username

Required. Username of the BridgePay Merchant.

NSString;
Min Value = 5;
Max Value = 25

Password

Required. Password of the BridgePay Merchant.

NSString
Min Value = 7;
Max Value = 25

MerchantCode

Required. BridgePay Merchant Code.

NSString
Numeric (0-9)

MerchantAccountCode

Required. BridgePay Merchant Account Code.

NSString
Numeric (0-9)

IndustryType

Required. Indicates the Industry type of the merchant assigned to a transaction.
Valid values:
TRANSACTION_INDUSTRY_TYPE_RETAIL
TRANSACTION_INDUSTRY_TYPE_RESTAURANT
TRANSACTION_INDUSTRY_TYPE_ECOMMERCE
TRANSACTION_INDUSTRY_TYPE_DIRECT_MARKETING
TRANSACTION_INDUSTRY_TYPE_LODGING
TRANSACTION_INDUSTRY_TYPE_HEALTHCARE

NSString;
Constant – valid values are listed.

healthCareData

Required. Represents the inclusion of Healthcare
related fields. Valid values are:
nil (indicates no Healthcare related fields present)
healthCareAmt (NSDecimalNumber). The portion 
of the Total Amount spent on healthcare related services or products.
transitAmt (NSDecimalNumber). The portion of the Total Amount spent on healthcare related transportation.
prescriptionAmt (NSDecimalNumber). The portion of the Healthcare Amount spent on prescription drugs 
or products.
visionAmt (NSDecimalNumber). The portion of the Healthcare Amount spent on vision related medical 
services.
dentalAmt (NSDecimalNumber). The portion of the
Healthcare Amount spent on dental related medical
services.
clinicAmt (NSDecimalNumber). The portion of the Healthcare Amount spent on hospitalization.
isQualifiedIIAS (NSString). Indicates whether purchase items are verified against IIAS as qualified for healthcare purchases. Can be lower case ‘true’, or lower case ‘false’.
 

NSString; or NSDecimalNumber (as indicated)
Min Value = 1;
Max Value = 50

PnRefNum

Gateway transaction ID/Previous transaction reference number. Only required for voids, refunds, and tip adjustments.

NSString;
Min Value = 1;
Max Value = 15

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.

NSString;
Min Value = 1;
Max Value = 15

PaymentAccountNumber

Card Number.

NSString;
Min Value = 13;
Max Value = 16

ExpirationDate

Card number expiration date in MMYY format.

NSString;
Min Value = 4;
Max Value = 4

ShippingAddress

Optional. Nested elements used to specify Shipping
information. REQUIRED FOR LEVEL II/III.

Name: Shipping address name. Max Length = 100

Street: Shipping address street. Max String Length =128

City: Shipping address city. Max Length = 50

State: Shipping address state. Max Length = 2

Zip: Shipping address postal codes. Accepted formats are US, UK, and Canadian postal codes. Max Length =15

CountryCode: Shipping address ISO country code. Max Length = 2
 

BPNAddress;
NSString;
Valid formats and values are as listed.

TerminalCommConfig

Required. Used to specify terminal configurations.

terminalType (NSString). Valid values are:
nil (indicates no terminal used)
TERMINAL_TYPE_INGENICO_BLUETOOTH
TERMINAL_TYPE_INGENICO_IP
TERMINAL_TYPE_MAGTEK_IDYNAMO
TERMINAL_TYPE_IDTECH_SHUTTLE
TERMINAL_TYPE_IDTECH_UNIPAYIII
TERMINAL_TYPE_IDTECH_UNIPAY_BT
TERMINAL_TYPE_BBPOS_CHIPPER2
TERMINAL_TYPE_BBPOS_WISEPAD2

ipAddress (NSString). Conditional. Used to specify the IP Address when the terminal type is TERMINAL_TYPE_INGENICO_IP

port (NSString). Conditional. Used to specify the port of an IP Terminal when the terminalType value is set to: TERMINAL_TYPE_INGENICO_IP. The port value is “12000” by default.

softwareVendor (NSString). Optional. Contact BridgePay integrations to obtain your hosting software value.

disableEmv (BOOL). Optional. Used to test non-EMV transactions.

useQuickChip (BOOL). Optional. Only available for terminals running RBA 23.0.2 or greater.

useBluefinManualEntry (BOOL). Optional. Used to prompt the terminal for manual card entry. Only available for terminals running RBA.

enableBluefinCashback (BOOL). Optional. Used to prompt for cashback on the terminal. Only available for terminals running RBA.

enableBluefinTip(BOOL). Optional. Used to prompt for tip amount on the terminal. Only available for terminals running RBA.

enableContactless(BOOL). Optional. Used to enable contactless EMV.

promptZipForFees(BOOL). Optional. Used to enable prompt for zip code entry on terminals running RBA, when a service or convenience fee is applied.

promptCvvForFees(BOOL). Optional. Used to enable prompt for CVV code entry on terminals running RBA, when a service or convenience fee is applied.

terminalTimeout(NSNumber). Optional. Specifies the number of seconds before a transaction should timeout.

NSString; Constant – valid values are listed.

TestMode

Gateway testing mode flag.

Boolean;
Value = Yes or No

TpiUrl

Optional. URL linking to the legacy, non-EMV capable gateway.

NSString

Token

Represents the tokenized card number received from a token request. Used in place of the PaymentAccountNumber.

NSString;
Value = 22 characters

BankAccountNumber

The account number to use in a check transaction.

NSString;
Value = 17 characters

RoutingNumber

The routing number to use in a check transaction.

NSString;
Vaule = 9 characters

PartialApproval

Indicates whether or not a transaction is a partial approval.

Boolean;
Value = Yes or No

EnableTpi

Use the legacy, non-EMV capable gateway.

Boolean;
Value = Yes or No

SignatureData

Base 64 encoded signature.

NSString

DisableAmountConfirmation

Disables the amount confirmation prompt on the terminal for credit transactions.

Boolean;
Value = Yes or No

enforceCardType

Optional. Enforces Debit/Credit card types for Debit/Credit tender types based on whether Debit AID or Credit AID are present.

BOOL

taxRate

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

NSDecimalNumber

taxAmount

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

NSDecimalNumber

taxIndicator

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

NSString;
Max Value = 1

voiceAuthCode

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

NSString;
Max Value = 15

cardPresent

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

TRUE = Card Present
FALSE = Card Not Present

Note: value is set to TRUE by default.

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

Note: value is set to FALSE by default.

Boolean

PublicKey

The private key assigned to the merchant for use with TokenPay.

NSString;
Max Value = 36

PrivateKey

The private key assigned to the merchant for use with TokenPay.

NSString;
Max Value = 36

AuthenticationTokenId

The secure PCI token generated by TokenPay.

NSString;
Max Value = 36

ClerkId

The ID of the clerk currently logged in.

NSString;
Max Value = 15

TipRecipientCode

Server ID for the customer.

NSString;
Max Value = 15

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

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

NSString;
Max Value = 1

customFields

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

NSString;
Min = 20
Max Value = 500

bridgeCommURL

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

URL String
 

Alternatively, the default constructor can be used if the required fields are set afterwards:

PayGuardianTransaction

The construction for a PayGuardianTransaction is:

The run method with completion is:

The completion must be implemented to capture the results of a transaction request. The blocks available for implementation are onStateChanged (transaction) , onReaderStateChanged (device status), and onCardDataAvailable (BIN lookup). The device status and BIN lookup blocks are optional. If the cardDataAvailable block is implemented you must call resumeCardRead or cancel on the PayGuardianTransaction object or else the transaction will time out.

BPNPayment

The BPNPayment is the response from a PayGuardianTransaction. It contains two fields: BridgeCommResponse and BPNReceipt. The BridgeCommResponse contains the gateway response fields and the BPNReceipt contains the fields necessary for an EMV compliant receipt.

BridgeCommResponse

The BridgeCommResponse object contains the following properties that can be returned in the response originating from the BPNPaymentRequest.

Property

Description

Data Type / Min - Max Values

Property

Description

Data Type / Min - Max Values

TransactionId

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

NSString
Max Value = 15

RequestType

Returns the 3 digit value for the type of BridgeComm request message submitted. 

Valid values are:
'004' = Authorization request
'001' = Multi-use token request
'007' = Change password request
'011' = Merchant info request
'012' = Void/Refund request
'014' = Manage gift card request
'015' = Account inquiry request
'019' = Capture request
'020' = Settlement initiation request
'023' = Find transaction request

NSString
Max Value = 15

ResponseCode

BridgeCommResponseCodeSuccess = 0
BridgeCommResponseCodeCancel = 1
BridgeCommResponseCodeError = 2
BridgeCommResponseCodeDeniedByCustomersBank = 30032

Enum
Max Vaule =6

ResponseDescription

Plain text response message.

NSString
N/A

Token

Unique token assigned to a transaction.

NSString
Max = 22

ExpirationDate

Card expiration date.

NSString
Max = 7

AuthorizationCode

Authorization code for a transaction.

NSString
Max = 50

OriginalReferenceNumber

Original reference number from a request.

NSString
Max = 12

AuthorizedAmount

Amount authorized by the processor.

NSDecimalNumber
Max = 12

OriginalAmount

Original requested amount of the transaction.

NSDecimalNumber
Max = 12

GatewayTransactionID

Unique ID of a transaction in the gateway.

NSString
Max = 12

GatewayMessage

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

NSString
Max = 50

InternalMessage

Internal Message from the gateway.

NSString
Max = 50

GatewayResult

Result message from the gateway.

NSString Max = 5

AVSMessage

AVS Match Result Message.

NSString Max = 10

AVSResponse

AVS Response Code.

NSString Max = 10

CVMessage

CVV/CVV2 Match Result Message.

NSString Max = 10

CVResult

CVV/CVV2 Result code.

NSString Max = 10

TransactionCode

Reserved for future use.

NSString

TransactionDate

Date/time of the transaction.

NSString Max = 10

RemainingAmount

Amount remaining of the original amount.

NSDecimalAmount
Max = 12

ISOCountryCode

Country code for currency.

NSString
Max = 3

ISOCurrencyCode

Currency code for a transaction.

NSString
Max = 3

ISOTransactionDate

Date of transaction from the processor.

NSString
Max = 10

ISORequestDate

Date of request at a processor.

NSString
Max = 10

NetworkReferenceNumber

Unique ID of a transaction at the processor.

NSString
Max = 12

NetworkCategoryCode

Processor specific category code.

NSString
Processor dependent

NetworkMerchantId

Merchant ID from the gateway.

NSString
Processor dependent

NetworkTerminalId

Network terminal ID from the gateway.

NSString
Processor dependent

CardType

Reserved for future use. Type of card.

NSString

MaskedPAN

Reserved for future use. Masked card number.

NSString

IsCommercialCard

“True” or “False”

NSString

StreetMatchMessage

Reserved for future use. Message about street match for AVS.

NSString

SecondsRemaining

Reserved for future use.

NSString

MerchantCode

Gateway merchant code used in a transaction.

NSString
Numeric (0-9)

MerchantAccountCode

Gateway merchant account code used in a transaction.

NSString
Numeric (0-9)

MerchantName

Name of a merchant.

NSString
Max = 50

ReceiptTagData

EMV tag data. Processor dependent.

NSString

IssuerTagData

EMV issuer tag data. Processor dependent.

NSString

ApplicationIdentifier

Reserved for future use.

 

TerminalVerificationResults

Reserved for future use.

 

IssuerApplicationData

Reserved for future use.

 

TransactionStatusInformation

Reserved for future use.

 

AuthenticationTokenId

The secure PCI token generated by TokenPay.

NSString; Max Value = 36

WalletId

The wallet ID.

NSString; Max Value = 36

WalletPaymentMethodId

The wallet payment method ID.

NSString; Max Value = 36

WalletResponseMessage

The wallet response message. 

NSString; Max Value = 100

WalletResponseCode

The wallet response code.

NSString; Max Value = 2

BPNReceipt

The EMV compliant receipt components returned in the BPNPayment object.

Property

Description

Data Type / Min - Max Values

Property

Description

Data Type / Min - Max Values

MaskedCardNumber

PA-DSS masked card number for the transaction.

NSString
Min = 13;
Max = 19

ChipCardAID

Reserved for future use.

NSString

Invoice

Invoice number from transaction.

NSString Min = 1/Max = 24

Seq

Sequence number

NSString

AuthorizationCode

Gateway authorization code.

NSString
Min = 5;
Max = 50

EntryMethod

Card number entry method.

NSString
Max = 50

TotalAmount

Total amount of the transaction.

NSDecimalNumber
Max = 12

AppLabel

Name of application

NSString
Max = 50

CardHolderName

Name on the card

NSString
Min = 1;
Max = 50

NetworkMerchantID

Merchant ID. Dependent on processor.

NSString

NetworkTerminalID

Terminal ID. Dependent on processor.

NSString

CardFirstFour

First four digits of a card

NSString
Min = 4;
Max = 4

CardType

Type of card

NSString
Min = 4;
Max = 4

Sample Examples

Basic transaction request / response and receipt output examples.

MSR Sale Type Request

An example of a basic MSR sale transaction request. The onReaderStateChanged and onCardDataAvailable blocks are optional events that can be subscribed to.

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

Capture Transaction Type with Tip Request

An example of a basic capture transaction request that includes a tip amount in the summary total.

Capture Transaction Type with Tip Response

An example of a basic capture transaction response that includes a tip amount in the summary total.

Capture Transaction with Tip Receipt

An example of the values returned on a basic capture transaction receipt that includes a tip amount in the summary total.

Tip Adjust Transaction Type Request

Tip adjust now allows an adjustment to a zero dollar tip. In addition, you can now do a tip adjust to a sale-auth that has been captured and is in an open batch. 

An example of a basic transaction request that adds or updates a Tip Amount into a Sales Transaction and sums both amounts into the summary total of the transaction. Can only be performed on an unsettled Sale transaction. 

Tip Adjust Transaction Type Response

An example of a basic tip adjust transaction.

Sale Transaction Type Request using a Token

An example of a basic sale transaction using a token to replace the payment card.

Sale using Token Transaction Response

An example of a basic sale transaction response where a token was submitted in the transaction request.

Sale using Token Receipt

An example of the values returned on a basic sale transaction where a token was submitted in the transaction request.

Invalid Tender Type Request

An example of how to submit a sale transaction with an unacceptable tender type.

Invalid Tender Type Response

An example of a sale transaction response error where an unacceptable tender type was processed.

Cancel Transaction Request

An example of how to submit a sale transaction to simulate the cancellation of a transaction after the transaction has been initiated.

Cancel Transaction Error Response

An example of a cancelled sale transaction error response where the cancellation of a transaction occurred after the transaction was initiated.

Sale Transaction Type Request using an AuthenticationTokenID

An example of a basic sale transaction using a token to replace the payment card.

Terminal Sale Type Request

An example of a terminal sale type request using the shorthand constructor.

Token Type Request

An example of a token type request using the shorthand constructor.

Token Sale Request

An example of a Token Sale request using the shorthand constructor.

Find Transaction Type Request

An example of a Find Transaction Type request using the shorthand constructor.

Card Verification Type Request

An example of a card verification transaction request, used to verify the validity of a card number with the cardholder’s bank prior to authorizing the card for payment.

EMV Transaction Support

EMV Implementation Details

PayGuardian also supports EMV transactions. Upon receiving the transaction request, PayGuardian calls the device to obtain the card information. The device will prompt to Swipe or Insert the Card. Upon the card insertion or card swipe, the transaction will be processed according to the user selection.

Minimum Requirement:
Card Reader Version: 23.02 RBA
When a transaction is being processed as an EMV transaction, the communication messages between the Card Reader device and the PayGuardian Application are uniquely identified by a “33.” message identifier. There are currently seven message types used during EMV transactions. The message type is selected using a subcommand identifier which is embedded in the message. Subcommand identifiers are used to identify the different message types:

  1. EMV Transaction Initiation Message

    1. The '00.' EMV Transaction Initiation message is sent from the PayGuardian to the device to indicate the type of transaction purchase.

  2. EMV Track 2 Equivalent Data Message

    1. The '02.' EMV Track 2 Equivalent Data message is sent from the device to the PayGuardian. This data is similar to the Track 2 data which is stored on a magnetic stripe card.

  3. EMV Authorization Request Message

    1. The '03.' EMV Authorization Request message is sent from the device to the PayGuardian to provide the cryptographic  information necessary to authorize the transaction.  The authorization process is initiated by the device issuing a request to the PayGuardian.

  4. EMV Authorization Response Message

    1. The '04.' EMV Authorization Response message is sent from the PayGuardian to the device in response to the EMV Authorization Request message. This message includes cryptographic information which is read by the embedded microchip on the card.

  5. EMV Authorization Confirmation Response Message

    1. The '05.' EMV Confirmation Response message is sent from the device to the PayGuardian, and contains the results from applying the authorization data to the embedded microchip on the EMV card.

EMV Purchase Transaction Flow

This section describes the message flow for EMV transactions once PayGuardian receives the transaction request from the mPOS application.

  • PayGuardian will activate the Device based on the terminal type specified in the transaction payment request.

  • The card number, expiration date, and cardholder name will be transmitted in the transaction request through the Device (Ingenico terminals will prompt for amount
    confirmation).

  • The transaction response will be returned to PayGuardian and to the Device. If the Device has a signature capture pad, the customer will be prompted to Sign and Accept on the Device.

  • If the electronic signature is captured, it will be returned encoded in the response object.

  • Remove the EMV card from the Device.

Sample EMV Sale Request

An example of a basic EMV sale transaction request.

Sample EMV Sale Response

An example of a basic EMV sale transaction response.

Sample EMV Sale Receipt

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

Appendix

Response Values

Result Codes

The following table contains descriptions of the result codes returned in the ResultCode response field from PayGuardian. Please note that when programmatically validating the result of a transaction, you should use this value instead of any other response message describing the result.

Value

Description

Value

Description

0

Approved.

1

Cancelled. Review ResultTxt field in PaymentResponse to determine why the transaction was not processed.

2

Declined. Review ResultTxt field in PaymentResponse to determine why the transaction was not processed.

AVS Response Codes

Value

Description

Value

Description

00

AVS Error - Retry, System unavailable, or Timed out

40

Address not available (Address not verified)

43

Street address not available (not verified), ZIP matches

44

Address failed

45

Street address and Zip don't match

46

Street address doesn't match, 5-digit ZIP matches

47

Street address doesn't match, 9-digit ZIP matches

4A

Street address or ZIP doesn't match

4D

Street address matches, ZIP does not

4E

Street address and 5-digit ZIP matches

4F

Street address and ZIP match

53

Account holder name incorrect, billing postal code matches

55

Unrecognized response - Account holder name, billing address, and postal code are all incorrect

5C

Account holder name incorrect, billing address matches

5F

Account holder name incorrect, billing address and postal code match

70

Account name matches

73

Account holder name and billing postal code match 

7C

Account holder name and billing address match

7F

Account holder name, billing address and postal code match

80

AVS service not supported by issuer – Issuer doesn’t participate in AVS

CV Response Codes

The following table contains the possible descriptions of the response values returned for a CVV2/CVC2/CID check in the CvResponse response field from PayGuardian.

Please Note: If the response returned is blank for this specific field tag, it is possible that your selected processor does not support the full range of CVV response codes.

Value

Description

Value

Description

M

CVV2/CVC2/CID - Match

N

CVV2/CVC2/CID - Match

P

Not Processed.

S

Issuer indicates that the CV data should be present on the card, but the merchant has indicated that the CV data is not present on the card.

U

Unknown. Issuer has not certified for CV or issuer has not provided Visa/MasterCard with the CV encryption keys.

X

Unrecognized reason. Server provided did not respond.

Errors

iOS App Extension Errors

Result Code

Description

Result Code

Description

E1001

Invalid invoice number.

E1002

Invalid amount.

E1003

Invalid username.

E1004

Invalid password.

E1005

Invalid merchant code.

E1006

Invalid merchant account code.

E1007

Invalid tender type.

E1008

Invalid transaction type.

E1009

Invalid payment request

E1010

Invalid reference number.

E1011

No network connection.

E1012

Device not found.

E1013

Xml deserialization error.

E1014

Xml serialization error.

E1015

Xml base64 encode error.

E1016

Xml base64 decode error.

E1017

Unable to process transaction.

E1018

Unable to process transaction.

E1019

Transaction cancelled. Device TimedOut.

E1020

Transaction cancelled. 

Additional Feature Information

HealthCare Support

PayGuardian also provides support for healthcare industry transactions (FSA or HSA accounts) through use of the Extended Data fields. The additional healthcare specific fields and associated amounts will need to be specified only when the required healthCareData (see page 11) element is populated with a value other than ‘nil’ (indicates that healthcare data will be present as part of the transaction request). The only required parameter value within the healthCareData element is healthCareAmt; all other healthcare specific parameters are optional. If medical transportation was included as a value, then the transitAmt parameter should be added.

Depending on the type of service rendered, additional amounts can be specified to healthCareAmt to indicate how much was spent on prescription, vision, dental, and clinic/hospitalization services. The total of prescription, vision, dental and clinic amounts can be less than or equal to healthCareAmt.

Property

Description

Data Type / Min - Max Values

Property

Description

Data Type / Min - Max Values

healthCareAmt

Required. The portion of the Total Amount spent on healthcare related services or products.

(Format example: http://DDDD.CC )

NSDecimalNumber (as indicated)
Min Value = 1;
Max Value = 50

transmitAmt

Optional. Indicates the portion of the total amount spent on healthcare-related transportation.

(Format example: http://DDDD.CC )

NSDecimalNumber (as indicated)
Min Value = 1;
Max Value = 50

prescriptionAmt

Optional. Indicates the portion of the Healthcare Amount spent on prescription drugs or products.

(Format example: )

NSDecimalNumber (as indicated)
Min Value = 1;
Max Value = 50

VisionAmt

Optional. Indicates the portion of the Healthcare Amount spent on vision related medical services.

(Format example: )

NSDecimalNumber (as indicated)
Min Value = 1;
Max Value = 50

DentalAmt

Optional. Indicates the portion of the Healthcare Amount spent on dental related medical services.

(Format example: )

NSDecimalNumber (as indicated)
Min Value = 1;
Max Value = 50

ClinicAmt

Optional. Indicates the portion of the Healthcare Amount spent on hospitalization.

(Format example: )

NSDecimalNumber (as indicated)
Min Value = 1;
Max Value = 50

IsQualifiedIIAS

Optional. Indicates whether purchase items are verified against IIAS as qualified for healthcare purchases. Can be lower case ‘true’, or lower case ‘false’

NSString
(as indicated)
Min Value = 4;
Max Value = 5

Examples

Sale Type Request using HealthCare Data

An example of a basic sale transaction request with healthcare elements

Sale Transaction using HealthCare Data Response

An example of a basic sale transaction response when Healthcare Data is present in the request.
(Please note that the Healthcare fields are not returned in the response message)

Sale Receipt for Transaction using HealthCare Data

An example of a basic sale receipt when Heathcare Data is present in the request.
(Please note that the Heathcare fields are not returned on the receipt).

Test Cards and Data

Swiped / MSR Test Transaction Info

The following test card numbers are required for use in both integration testing and certification for PayGuardian iOS, but only for ‘NON-EMV TRANSACTIONS’ (a separate test account will be provided for EMV transaction testing):

Test Cards & Bank Accounts

The following page provides test card information

Test Amount Ranges

The following page provides information on test amount ranges

More Information

Table of Contents

Property of BridgePay Network Solution ©2023