PayGuardian iOS SDK
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.
Test Application (For use in TestFlight)
PayGuardian iOS Release Notes
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:
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 iOS Framework library.
The payment screen loads and prompts the user to enter customer and payment data.
After collecting all transaction information, PayGuardian transmits the data to the server.
After receiving a response from the host, the payment screen returns the processing results back to the mPOS system.
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 |
|---|---|---|
Amount | Required. Total transaction amount (includes subtotal, cash back, tax, and tip) (Format example: DDDD. CC) | NSDecimalNumber |
TipAmount | The tip amount. The tip is not added into the total amount, it is an in-addition-to the specified amount. | NSDecimalNumber |
InvoiceNumber | Required. POS system invoice/tracking number. (Alpha/Numeric characters only) | NSString |
TenderType | Required. Valid values are: TENDER_TYPE_CREDIT, | NSString; |
TransactionType | Required. Valid values are: | NSString; |
Username | Required. Username of the BridgePay Merchant. | NSString; |
Password | Required. Password of the BridgePay Merchant. | NSString |
MerchantCode | Required. BridgePay Merchant Code. | NSString |
MerchantAccountCode | Required. BridgePay Merchant Account Code. | NSString |
IndustryType | Required. Indicates the Industry type of the merchant assigned to a transaction. | NSString; |
healthCareData | Required. Represents the inclusion of Healthcare | NSString; or NSDecimalNumber (as indicated) |
PnRefNum | Gateway transaction ID/Previous transaction reference number. Only required for voids, refunds, and tip adjustments. | NSString; |
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; |
PaymentAccountNumber | Card Number. | NSString; |
ExpirationDate | Card number expiration date in MMYY format. | NSString; |
ShippingAddress | Optional. Nested elements used to specify Shipping 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; |
TerminalCommConfig | Required. Used to specify terminal configurations. terminalType (NSString). Valid values are: 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; |
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; |
BankAccountNumber | The account number to use in a check transaction. | NSString; |
RoutingNumber | The routing number to use in a check transaction. | NSString; |
PartialApproval | Indicates whether or not a transaction is a partial approval. | Boolean; |
EnableTpi | Use the legacy, non-EMV capable gateway. | Boolean; |
SignatureData | Base 64 encoded signature. | NSString |
DisableAmountConfirmation | Disables the amount confirmation prompt on the terminal for credit transactions. | Boolean; |
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; |
voiceAuthCode | Optional. Authorization Code for Voice Authorizations only when authorization was achieved outside of the network (by phone or other means). | NSString; |
cardPresent | Optional. When set to ‘TRUE’, the transaction is treated as a Card Present transaction. Valid values are: TRUE = Card 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 Note: value is set to FALSE by default. | Boolean |
PublicKey | The private key assigned to the merchant for use with TokenPay. | NSString; |
PrivateKey | The private key assigned to the merchant for use with TokenPay. | NSString; |
AuthenticationTokenId | The secure PCI token generated by TokenPay. | NSString; |
ClerkId | The ID of the clerk currently logged in. | NSString; |
TipRecipientCode | Server ID for the customer. | NSString; |
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 | The period for which a Sale-Auth transaction settlement is delayed. | NSString; |
customFields | Optional. The ability to pass custom user defined fields to the gateway via a XML string. | NSString; |
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: | URL String |
The constructor of the BPNPaymentRequest object is:
- (instancetype) initInvoiceNumber: (NSString *_Nonnull) invoiceNumber
pnRefNum: (NSString *_Nullable) pnRefNum
amount: (NSDecimalNumber *_Nullable) amount
tipAmount: (NSDecimalNumber *_Nullable) tipAmount
cashBackAmount: (NSDecimalNumber *_Nullable) cashBackAmount
tenderType: (NSString *_Nonnull) tenderType
transactionType: (NSString *_Nonnull) transactionType
username: (NSString *_Nonnull) username
password: (NSString *_Nonnull) password
merchantCode: (NSString *_Nonnull) merchantCode
merchantAccountCode: (NSString *_Nonnull) merchantAccountCode
paymentAccountNumber: (NSString *_Nullable) paymentAccountNumber
token: (NSString *_Nullable) token
expirationDate: (NSString *_Nullable) expirationDate
terminalCommConfig: (TerminalCommConfig *_Nonnull) terminalCommConfig
industryType: (NSString *_Nonnull) industryType
healthCareData: (BPNHealthCare *_Nullable) healthCareData
bankAccountNumber: (NSString *_Nullable) bankAccountNumber
routingNumber: (NSString *_Nullable) routingNumber
partialApproval: (BOOL) partialApproval
enableTpi: (BOOL) enableTpi
signatureData: (NSString *_Nullable) signatureData
disableAmountConfirmation: (BOOL) disableAmountConfirmation
testMode: (BOOL) testMode;Alternatively, the default constructor can be used if the required fields are set afterwards:
_request = [BPNPaymentRequest alloc];
[_request setInvoiceNumber: (NSString *_Nonnull) invoiceNumber];
[_request setAmount: (NSDecimalNumber *_Nullable) amount];
[_request setTenderType: (NSString *_Nonnull) tenderType];
[_request setTransactionType: (NSString *_Nonnull) transactionType];
[_request setUsername: (NSString *_Nonnull) username];
[_request setPassword: (NSString *_Nonnull) password];
[_request setMerchantCode: (NSString *_Nonnull) merchantCode];
[_request setMerchantAccountCode: (NSString *_Nonnull) merchantAccountCode];
[_request setTerminalCommConfig: (TerminalCommConfig *_Nonnull) terminalCommConfig];
[_request setIndustryType: (NSString *_Nonnull) industryType];PayGuardianTransaction
Property of BridgePay Network Solution ©2025