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 8.0 and above

iOS Application Setup Guide

Minimum Requirements

iPad/iPhone device with iOS 8.0 and above
iPad/iPhone device must have the Bluetooth connectivity feature.

ℹ️ iPad/iPhone devices with iOS 11.0 or above must use PayGuardian iOS framework versions, 2.4.1 or higher.

Project Dependencies

To integrate to BridePay's PayGuardian iOS, please begin by reviewing the PayGuardian iOS Developer Guide. 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

PayGuardian iOS Release Notes

PayGuardian iOS Developer Guide

Certified Devices

ID TECH Upgrade Tool

Apple MFI Submission Form

The Apple MFI Submission Form needs to be completed and submitted prior to submitting to the Apple App Store. For reference, here is an example MFI Submission Form. Set the "Device protocol names used by this App" to com.ingenico.easypayemv.spm-transaction.

Send the completed form to: Zohaib Khan at Zohaib.Khan@ingenico.com

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

PayGuardian_SDK.framework
Ono.framework
RBA_SDK.framework
ID TECH_UniMag.a
libMTSCRA.a

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
libstdc++.tbd

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

Device Configuration

ℹ️ iOS device and card reader must be connected through the audio Jack, accessory port, or bluetooth pairing connectivity.

Ingenico

How to connect iOS device and card reader device?

Bluetooth Supported Devices: iCMP and iSMP4

Use Card Reader Version: 23.02 RBA

Hit the “F” button four times quickly; the device will beep and return to the Bluetooth Pairing Screen. Bluetooth pairing can begin from the Bluetooth Pairing Screen.

Restart the device by simultaneously pressing and holding the [.,#*] and [Yellow] keys until the device beeps.
Wait for the device to display the RBA or UIA initialization screen.
When the RBA or UIA initialization screen appears, quickly press the [2] [6] [3] [4] [Green] [F] [F] keys.
If successful, the Functions menu should appear. If the Functions menu does not appear, return to Step 1 and restart the device.
Select the Bluetooth pairing options and select the iOS device from the list to connect the card reader unit.

Ethernet Supported Devices: iPP320 and iPP350

Use Card Reader Version: 23.02 RBA

To start, reboot the device and upon a successful reboot, follow the steps below:

Reboot the device using the # and yellow key.
On the copyright screen, press 2634 and then press the green key.
Press the "F" button.
Navigate to 3-TDA > 0-Configuration > 0-Communication > 0-Select Comm, and Type “Select 2-Ethernet”.
Return to the previous menu by pressing the red key.
Navigate to “2-Ethernet Settings”, and select “10-IP Display”.
Select “1-Yes”, and press the yellow key to return to the previous menu.

To allow the terminal to automatically receive an IP Address:

Navigate to 2-DHCP, and select “0-Auto”
Press the yellow key to return to the previous menu

To manually assign an IP Address:

Navigate to 2-DHCP, and select “1-Static, then press the yellow key to return to the previous menu
Select 3-IP Address, and enter the desired IP, then press the green key to save and return to the previous menu
Hit the red key three times. On the "Save and Reboot" prompt, select “1-Yes”
Allow the device to boot.
A "UPOS Interface Applicaton" screen should appear.
Use the F2 key to scroll down to the bottom
Note your IP Address and port number next to "Ethernet:Server:DHCP". These values should be used in the TerminalCommConfig object.

ID TECH

How to connect iOS device and card reader device?

Audio Jack Supported Devices: UniMag, Shuttle, and VP3300 (formerly Unipay III)

The iOS device and card reader device should be connected through the audio jack on the iOS device.

BLE Supported Devices: VP3300 (formerly Unipay III)
BLE scanning will be auto-enabled when Terminal_Type_IDTECH_UNIPAY_BT is transmitted as the "terminalType" value in the TerminalCommConfig object. The Apple iOS scans and locates all BLE devices within range, and presents a list for the PayGuardian SDK to choose from. To connect via bluetooth, turn on the device bluetooth pairing and PayGuardian will do the rest.

ℹ️ The default friendly name of "Enzytek_SPS_S" must not be changed as PayGuardian uses this to identify the device.

MagTek

How to connect iOS device and card reader device?

Audio Jack Supported Devices: iDynamo

The iOS device and card reader should be connected through the audio jack on the iOS device.

BBPOS

How to connect iOS device and card reader device?

Audio Jack Supported Devices: Chipper 2

The iOS device and card reader should be connected through the audio jack on the iOS device.

Bluetooth Supported Devices: WisePad 2, WisePad 2 Plus, and Chipper 2X BT

The iOS device and card reader should be paired through the bluetooth connection.

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 located on the BridgePay Integrator Support Portal.

Please use the BridgePay Integrations Support Portal to register for a new user support account at from which you can request to receive a set of test cards for integrations that include EMV chip / swiped, card- present transactions (Credit, Debit, EBT, Gift Cards). You’ll also be able to access the Developer Support Knowledgebase, request support assistance with integration questions, as well as create, access, and track your support cases.

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

iOS Framework Integration

Programmatically, a transaction is comprised of a four step process:

Create a BPNPaymentRequest object.
Pass the BPNPaymentRequest object to the constructor of a PayGuardianTransaction object.
Call the runOnCompletion method and provide an implementation for the completion.
Implement a handler for the returned BPNPayment and/or NSError.

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

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

The construction for a PayGuardianTransaction is:

initWithPaymentRequest:(BPNPaymentRequest *)request;

The run method with completion is:

- (void)runOnCompletion: (void (^)(BPNPayment *payment, NSError *error)) onCompletion
onStateChanged: (void (^)(PayGuardianTransactionState state)) onStateChanged;

The completion must be implemented to capture the results of a transaction request.

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

  _request = [[BPNPaymentRequest alloc]
initInvoiceNumber: @”8888”
pnRefNum: nil
amount: [NSDecimalNumber decimalNumberWithString:@"5.50"]
tipAmount: nil
cashBackAmount: nil
tenderType: TENDER_TYPE_CREDIT 
transactionType: TRANSACTION_TYPE_SALE
username: @"emvpgtest"
password: @"57!sE@3Fm" 
merchantCode: @"320000"
merchantAccountCode: @"320001"
paymentAccountNumber: nil
token: nil
expirationDate: nil
terminalType: (Valid terminal type here)
industryType: TRANSACTION_INDUSTRY_TYPE_RETAIL 
healthCareData: nil
disableEMV: NO
testMode: YES];

_transaction = [[PayGuardianTransaction alloc] initWithPaymentRequest:_request];
[_transaction runOnCompletion: ^(BPNPayment *payment, NSError *error) {
//process response
} onStateChanged: ^(PayGuardianTransactionState state) {
//process state change
}];

MSR Sale Type Response

An example of a basic MSR sale transaction response.

BPNPayment.BridgeCommResponse:
transactionID: 8888
requestType: 004
responseCode: 0
responseDescription: Successful Request
token: 11110000000068530608
expirationDate: 1225
authorizationCode: 290144
originalReferenceNumber: MCC7754741020
authorizedAmount: $5.50
originalAmount: $5.50
gatewayTransactionID: 214973401
gatewayMessage: A01 - Approved
internalMessage: Approved: 290144 (approval code)
gatewayResult: 00000
AVSMessage:
AVSResponse:
CVMessage:
CVResult:
transactionCode: (null)
transactionDate: 20161020
remainingAmount: $0.00
ISOCountryCode: (null)
ISOCurrencyCode: USD
ISOTransactionDate: 2016-10-20 14:32:47.86
ISORequestDate: 2016-10-20 14:32:47.86
networkReferenceNumber: MCC7754741020
merchantCategoryCode:
networkMerchantID: 518564010126944
networkTerminalID: PPB01.
cardType: Mastercard
maskedPAN: 5***********0608
responseTypeDescription: sale
isCommercialCard: False
streetMatchMessage:
secondsRemaining: (null)
merchantCode: (null)
merchantAccountCode: (null)
merchantName: (null)
receiptTagData: (null)
issuerTagData: (null)
applicationIdentifier: (null)
terminalVerificationResults: (null)
issuerApplicationData: (null)
transactionStatusInformation: (null)

MSR Sale Receipt

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

BPNPayment.BPNReceipt:
maskedCardNumber: 5***********0608:
chipCardAID: (null) //← No AID for non-emv trx
invoice: 8888
seq: 8888
authorizationCode: 290144
entryMethod: Swipe_Read
totalAmount: 5.5
appLabel:
cardHolderName: (null)
networkMerchantId: 518564010126944
networkTerminalId: PPB01.
cardFirstFour: 5413
cardType: Mastercard
requiresSignature: YES
pinEntered: NO

Sale_Auth Transaction Type Request

An example of a basic authorization only transaction request.

_request = [[BPNPaymentRequest alloc]

initInvoiceNumber: @”33333”
pnRefNum: nil
amount: [NSDecimalNumber decimalNumberWithString:@"7.50"]
tipAmount: nil
cashBackAmount: nil
tenderType: TENDER_TYPE_CREDIT
transactionType: TRANSACTION_TYPE_SALE_AUTH
username: @"emvpgtest"
password: @"57!sE@3Fm"
merchantCode: @"320000"
merchantAccountCode: @"320001"
paymentAccountNumber: nil
token: nil
expirationDate: nil
terminalType: (Valid terminal type here)
industryType: TRANSACTION_INDUSTRY_TYPE_RETAIL
healthCareData: nil
disableEMV: NO
testMode: YES];

_transaction = [[PayGuardianTransaction alloc] initWithPaymentRequest:_request];
[_transaction runOnCompletion: ^(BPNPayment *payment, NSError *error) {
//process response
} onStateChanged: ^(PayGuardianTransactionState state) {
//process state change
}];

Sale_Auth Transaction Type Response

An example of a basic authorization only transaction response.

BPNPayment.BridgeCommResponse:
transactionID: 33333
requestType: 004
responseCode: 0
responseDescription: Successful Request
token: 11110000000077149269
expirationDate: 0325
authorizationCode: 786986
originalReferenceNumber:
authorizedAmount: $7.50
originalAmount: $7.50
gatewayTransactionID: 214972201
gatewayMessage: A01 - Approved
internalMessage: Approved: 786986 (approval code)
gatewayResult: 00000
AVSMessage:
AVSResponse:
CVMessage:
CVResult:
transactionCode: (null)
transactionDate: 20161020
remainingAmount: $0.00
ISOCountryCode: (null)
ISOCurrencyCode: USD
ISOTransactionDate: 2016-10-20 14:02:46.153
ISORequestDate: 2016-10-20 14:02:46.153
networkReferenceNumber:
merchantCategoryCode:
networkMerchantID: 518564010126944
networkTerminalID: PPB01.
cardType: Visa
maskedPAN: 4***********9269
responseTypeDescription: auth
isCommercialCard: False
streetMatchMessage:
secondsRemaining: (null)
merchantCode: (null)
merchantAccountCode: (null)
merchantName: (null)
receiptTagData: 4F:A0000000031010;95:8080008000;9F10:06010A03A00000;9B:6800;91:;8A:
issuerTagData:
applicationIdentifier: A0000000031010
terminalVerificationResults: 8080008000
issuerApplicationData: 06010A03A00000
transactionStatusInformation: 6800

Sale_Auth Receipt

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

BPNPayment.BPNReceipt:
maskedCardNumber: 4***********9269:
chipCardAID: A0000000031010
invoice: 33333
seq: 33333
authorizationCode: 786986
entryMethod: Chip_Read
totalAmount: 7.5
appLabel: VISA DEBIT
cardHolderName: CARDHOLDER/VALUED
networkMerchantId: 518564010126944
networkTerminalId: PPB01.
cardFirstFour: 4204
cardType: Visa
requiresSignature: YES
pinEntered: NO

Capture Transaction Type with Tip Request

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

 _request = [[BPNPaymentRequest alloc]
initInvoiceNumber: @”33333”
pnRefNum: @”214972201” //gatewayTransactionID from SALE_AUTH
amount: [NSDecimalNumber decimalNumberWithString:@"9.50"] //adjust amount with tip
tipAmount: [NSDecimalNumber decimalNumberWithString:@"2.00"] //tip amount for record
cashBackAmount: nil
tenderType: TENDER_TYPE_CREDIT
transactionType: TRANSACTION_TYPE_CAPTURE
username: @"emvpgtest"
password: @"57!sE@3Fm"
merchantCode: @"320000"
merchantAccountCode: @"320001"
paymentAccountNumber: nil
token: nil
expirationDate: nil
terminalType: nil
industryType: TRANSACTION_INDUSTRY_TYPE_RETAIL
healthCareData: nil
disableEMV: NO
testMode: YES];
_transaction = [[PayGuardianTransaction alloc] initWithPaymentRequest:_request];
[_transaction runOnCompletion: ^(BPNPayment *payment, NSError *error) {
//process response
} onStateChanged: ^(PayGuardianTransactionState state) {
//process state change
}];

Capture Transaction Type with Tip Response

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

BPNPayment.BridgeCommResponse:
transactionID: 33333
requestType: 019
responseCode: 0
responseDescription: Successful Request
token: (null)
expirationDate: (null)
authorizationCode: (null)
originalReferenceNumber:
authorizedAmount: $0.00
originalAmount: $0.00
gatewayTransactionID: 214972201
gatewayMessage: A01 - Approved
internalMessage: (null)
gatewayResult: 00000
AVSMessage: (null)
AVSResponse: (null)
CVMessage: (null)
CVResult: (null)
transactionCode: (null)
transactionDate: (null)
remainingAmount: $0.00
ISOCountryCode: (null)
ISOCurrencyCode: (null)
ISOTransactionDate: (null)
ISORequestDate: (null)
networkReferenceNumber: (null)
merchantCategoryCode: (null)
networkMerchantID: (null)
networkTerminalID: (null)
cardType: (null)
maskedPAN:
responseTypeDescription: (null)
isCommercialCard: (null)
streetMatchMessage: (null)
secondsRemaining: (null)
merchantCode: (null)
merchantAccountCode: (null)
merchantName: (null)
receiptTagData: (null)
issuerTagData: (null)
applicationIdentifier: (null)
terminalVerificationResults: (null)
issuerApplicationData: (null)
transactionStatusInformation: (null)

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.

BPNPayment.BPNReceipt:
maskedCardNumber: :
chipCardAID: (null)
invoice: 33333
seq: 33333
authorizationCode: (null)
entryMethod: (null)
totalAmount: (null)
appLabel:
cardHolderName: (null)
networkMerchantId: (null)
networkTerminalId: (null)
cardFirstFour: (null)
cardType: (null)
requiresSignature: NO
pinEntered: NO

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.

_request = [[BPNPaymentRequest alloc]
initInvoiceNumber: @”8888”
pnRefNum: @”235531904” //gatewayTransactionID from SALE
amount: nil //adjustment will be calculated at gateway from tip
tipAmount: [NSDecimalNumber decimalNumberWithString:@"2.00"] //tip amount for adjustment
cashBackAmount: nil
tenderType: TENDER_TYPE_CREDIT
transactionType: TRANSACTION_TYPE_TIP_ADJUST
username: @"emvpgtest"
password: @"57!sE@3Fm"
merchantCode: @"320000"
merchantAccountCode: @"320001"
paymentAccountNumber: nil
token: nil
expirationDate: nil
terminalType: nil
industryType: TRANSACTION_INDUSTRY_TYPE_RETAIL
healthCareData: nil
disableEMV: NO
testMode: YES];
_transaction = [[PayGuardianTransaction alloc] initWithPaymentRequest:_request];
[_transaction runOnCompletion: ^(BPNPayment *payment, NSError *error) {
//process response
} onStateChanged: ^(PayGuardianTransactionState state) {
//process state change
}];

Tip Adjust Transaction Type Response

An example of a basic tip adjust transaction.

BPNPayment.BridgeCommResponse:
transactionID: 8888
requestType: 004
responseCode: 00000
responseDescription: Successful Request
token: (null)
expirationDate: (null)
authorizationCode: 987090
ReferenceNumber:
authorizedAmount: $7.00
originalAmount: $5.00
gatewayTransactionID: 235531904
gatewayMessage: A12 – Tip Adjustment Posted
internalMessage: Tip Adjustment Posted
gatewayResult: 00000
AVSMessage: (null)
AVSResponse: (null)
CVMessage: (null)
CVResult: (null)
transactionCode: (null)
transactionDate: (null)
remainingAmount: $0.00
ISOCountryCode: (null)
ISOCurrencyCode: (null)
ISOTransactionDate: (null)
ISORequestDate: (null)
networkReferenceNumber: (null)
merchantCategoryCode: (null)
networkMerchantID: (null)
networkTerminalID: (null)
cardType: (null)
maskedPAN:
responseTypeDescription: (null)
isCommercialCard: False
streetMatchMessage: (null)
WalletID: (null)
WalletPaymentMethodID: (null)
WalletResponseCode: (null)
WalletResponseMessage: (null)

Sale Transaction Type Request using a Token

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

_request = [[BPNPaymentRequest alloc]
initInvoiceNumber: @”33333”
pnRefNum: nil
amount: [NSDecimalNumber decimalNumberWithString:@"8.00"]
tipAmount: nil
cashBackAmount: nil
tenderType: TENDER_TYPE_CREDIT
transactionType: TRANSACTION_TYPE_SALE
username: @"emvpgtest"
password: @"57!sE@3Fm"
merchantCode: @"320000"
merchantAccountCode: @"320001"
paymentAccountNumber: nil
token: @"11110000000077149269" // ← Token from a previous sale or auth
expirationDate: @”0325” //← expirationDate used with Token
terminalType: nil // ← terminalType not used with Token
industryType: TRANSACTION_INDUSTRY_TYPE_RETAIL
healthCareData: nil
disableEMV: NO
testMode: YES];

_transaction = [[PayGuardianTransaction alloc] initWithPaymentRequest:_request];
[_transaction runOnCompletion: ^(BPNPayment *payment, NSError *error) {
//process response
} onStateChanged: ^(PayGuardianTransactionState state) {
//process state change
}];

Sale using Token Transaction Response

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

BPNPayment.BridgeCommResponse:
transactionID: 33333
requestType: 004
responseCode: 0
responseDescription: Successful Request
token: 11110000000077149269
expirationDate: 0325
authorizationCode: 099912
originalReferenceNumber:
authorizedAmount: $8.F00
originalAmount: $8.00
gatewayTransactionID: 214972001
gatewayMessage: A01 - Approved
internalMessage: Approved: 099912 (approval code)
gatewayResult: 00000
AVSMessage:
AVSResponse:
CVMessage:
CVResult:
transactionCode: (null)
transactionDate: 20161020
remainingAmount: $0.00
ISOCountryCode: (null)
ISOCurrencyCode: USD
ISOTransactionDate: 2016-10-20 13:55:27.3
ISORequestDate: 2016-10-20 13:55:27.3
networkReferenceNumber:
merchantCategoryCode:
networkMerchantID: 518564010126944
networkTerminalID: PPB01.
cardType:
maskedPAN:
responseTypeDescription: sale
isCommercialCard: False
streetMatchMessage:
secondsRemaining: (null)
merchantCode: (null)
merchantAccountCode: (null)
merchantName: (null)
receiptTagData: (null)
issuerTagData: (null)
applicationIdentifier: (null)
terminalVerificationResults: (null)
issuerApplicationData: (null)
transactionStatusInformation: (null)

Sale using Token Receipt

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

BPNPayment.BPNReceipt:
maskedCardNumber: :
chipCardAID: (null)
invoice: 33333
seq: 33333
authorizationCode: 099912
entryMethod: (null)
totalAmount: 8
appLabel:
cardHolderName: (null)
networkMerchantId: 518564010126944
networkTerminalId: PPB01.
cardFirstFour: (null)
cardType:
requiresSignature: NO
pinEntered: NO

Invalid Tender Type Request

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

_request = [[BPNPaymentRequest alloc]
initWithAmount: [NSDecimalNumber decimalNumberWithString:@"7.00"]
tipAmount: nil
invoiceNumber: @"12345"
tenderType: @"abcd" //<----- Invalid Tender Type will fail validation
transactionType: TRANSACTION_TYPE_SALE
username: @"emvpgtest"
password: @"57!sE@3Fm"
merchantCode: @"320000"
merchantAccountCode: @"320001"
originalReferenceNumber: nil
connectionService: nil
connectionQueue: queue
cashBackAmount: nil
PaymentAccountNumber: nil
ExpirationDate: @""
shippingAddress: nil
DeviceType: @"icmp"
testMode: YES
withToken: @""];
 
_transaction = [[PayGuardianTransaction alloc]
initWithPaymentRequest:_request];
 
  [_transaction runOnCompletion: ^(BPNPayment *payment, NSError *error) {
  //process response

  } onStateChanged: ^(PayGuardianTransactionState state) {
  //process state change

  }];

Invalid Tender Type Response

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

NSError:

Error Domain= com.bridgepaynetwork.PayGuardian
Code= 2 "Invalid payment request"
UserInfo= {NSLocalizedDescription=Invalid payment request}

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.

_request = [[BPNPaymentRequest alloc]
initWithAmount: [NSDecimalNumber decimalNumberWithString:@"6.75"]
tipAmount: nil
invoiceNumber: @"7575"
tenderType: TENDER_TYPE_CREDIT
transactionType: TRANSACTION_TYPE_SALE
username: @"emvpgtest"
password: @"57!sE@3Fm"
merchantCode: @"320000"
merchantAccountCode: @"320001"
originalReferenceNumber: nil
connectionService: nil
connectionQueue: queue
cashBackAmount: nil
PaymentAccountNumber: nil
ExpirationDate: nil
shippingAddress: nil
DeviceType: nil
testMode: YES
withToken: nil];
_transaction = [[PayGuardianTransaction alloc]
initWithPaymentRequest:_request];

[_transaction runOnCompletion: ^(BPNPayment *payment, NSError *error) {
//process response

} onStateChanged: ^(PayGuardianTransactionState state) {
//process state change

}];

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.

Error Domain= com.bridgepaynetwork.PayGuardian
Code= 6 "Card failed to read"
UserInfo= {NSLocalizedDescription=Card failed to read}

Sale Transaction Type Request using an AuthenticationTokenID

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

terminalCommConfig.terminalType = nil; //no terminal used
_request = [[BPNPaymentRequest alloc]
initInvoiceNumber: @"invoiceID111"
pnRefNum: nil
amount: [NSDecimalNumber decimalNumberWithString:@"12.33"]
tipAmount: nil
cashBackAmount: nil
tenderType: TENDER_TYPE_DEBIT
transactionType: TRANSACTION_TYPE_PCI_TOKEN // token payment
username: @"User"
password: @"Password "
merchantCode: @"0000”
merchantAccountCode: @"0000"
paymentAccountNumber: nil
token: nil
expirationDate: nil
terminalCommConfig: terminalCommConfig
industryType: TRANSACTION_INDUSTRY_TYPE_RETAIL
healthCareData: nil
bankAccountNumber: nil
routingNumber: nil
partialApproval: YES
enableTpi: NO
tpiUrl: nil
signatureData: nil
disableAmountConfirmation: YES
testMode: YES];
[_request setPrivateKey:@"4H#########NXYu"];
[_request setAuthenticationTokenId:token]; // token from TokenPay.js form

Terminal Sale Type Request

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

_request = [[BPNPaymentRequest alloc]
init: _terminalCommConfig
username: @"username"
password: @"password"
merchantCode: @"000000"
merchantAccountCode: @"000001"
tenderType: TENDER_TYPE_CREDIT
industryType: TRANSACTION_INDUSTRY_TYPE_RETAIL
invoiceNumber: [formatter stringFromDate:[NSDate date]]
amount: [NSDecimalNumber decimalNumberWithString:@"12.00"]
tipAmount: [NSDecimalNumber decimalNumberWithString:@"3.00"]
cashBackAmount: nil
testMode: true];

_transaction = [[PayGuardianTransaction alloc] initWithPaymentRequest:_request];
[_transaction runOnCompletion:^(BPNPayment *payment, NSError *error) {
//process response
} onStateChanged:^(PayGuardianTransactionState state) {
//process state change
}];

Token Type Request

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

_request = [[BPNTokenRequest alloc]
initTokenRequest: @"username"
password: @"password"
merchantCode: @"000000"
merchantAccountCode: @"000001"
publicKey: @"publicKey"
paymentAccountNumber: @"0000000000000000"
expirationDate: @"0000"
testMode: true];

_transaction = [[PayGuardianTransaction alloc] initWithPaymentRequest:_request];
[_transaction runOnCompletion:^(BPNPayment *payment, NSError *error) {
//process response
} onStateChanged:^(PayGuardianTransactionState state) {
//process state change
}];

Token Sale Request

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

_request = [[BPNTokenRequest alloc]
initSaleRequest: @"username"
password: @"password"
merchantCode: @"000000"
merchantAccountCode: @"000001"
industryType: TRANSACTION_INDUSTRY_TYPE_RETAIL
privateKey: @"privateKey"
authenticationTokenId: @"authTokenId"
amount: [NSDecimalNumber decimalNumberWithString:@"12.00"]
testMode: true];
 
    _transaction = [[PayGuardianTransaction alloc] initWithPaymentRequest:_request];
    [_transaction runOnCompletion:^(BPNPayment *payment, NSError *error) {
    //process response
    } onStateChanged:^(PayGuardianTransactionState state) {
   //process state change

Find Transaction Type Request

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

_request = [[BPNFindRequest alloc]
init: @"username"
password: @"password"
merchantCode: @"000000"
merchantAccountCode: @"000001"
invoiceNumber: @"invoiceNumber"
gatewayTransID: @"gatewayTransId"
purchaseToken: @"purchaseToken"
testMode: true];
   
    _transaction = [[PayGuardianTransaction alloc] initWithPaymentRequest:_request];
    [_transaction runOnCompletion:^(BPNPayment *payment, NSError *error) {
    //process response
    } onStateChanged:^(PayGuardianTransactionState state) {
   //process state change

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.

_request = [[BPNPaymentRequest alloc]
initInvoiceNumber: @"8888"
pnRefNum: nil
amount: [NSDecimalNumber decimalNumberWithString:@"0.00"]
tipAmount: nil
cashBackAmount: nil
tenderType: TENDER_TYPE_CREDIT
transactionType: TRANSACTION_TYPE_ACCOUNT_VERIFICATION
username: @"emvpgtest"
password: @"57!sE@3Fm"
merchantCode: @"320000"
merchantAccountCode: @"320001"
paymentAccountNumber: nil
token: nil
expirationDate: nil
terminalType: (Valid terminal type here)
transactionType: TRANSACTION_INDUSTRY_TYPE_RETAIL
healthCareData: nil
disableEMV: NO
testMode: YES];
 
   
    _transaction = [[PayGuardianTransaction alloc] initWithPaymentRequest:_request];
    [_transaction runOnCompletion:^(BPNPayment *payment, NSError *error) {
    //process response
    } onStateChanged:^(PayGuardianTransactionState state) {
   //process state change
   }];

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:

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

_request = [[BPNPaymentRequest alloc]
initWithAmount: [NSDecimalNumber decimalNumberWithString:@"6.00"]
tipAmount: nil
invoiceNumber: @"12345"
tenderType: TENDER_TYPE_CREDIT
transactionType: TRANSACTION_TYPE_SALE
username: @"emvpgtest"
password: @"57!sE@3Fm"
merchantCode: @"320000"
merchantAccountCode: @"320001"
originalReferenceNumber: nil
connectionService: nil
connectionQueue: queue
cashBackAmount: nil
PaymentAccountNumber: nil
ExpirationDate: @""
shippingAddress: nil
DeviceType: @"icmp"
testMode: YES
withToken: @""];
 
 _transaction = [[PayGuardianTransaction alloc]
 initWithPaymentRequest:_request];

 [_transaction runOnCompletion: ^(BPNPayment *payment, NSError *error) {
 //process response

Sample EMV Sale Response

An example of a basic EMV sale transaction response.

BPNPayment.BridgeCommResponse:
transactionID: 12345
requestType: 004
responseCode: 0
responseDescription: Successful Request
token: 11110000000077149269
expirationDate: 0325
authorizationCode: 471130
originalReferenceNumber:
authorizedAmount: $6.00
originalAmount: $6.00
gatewayTransactionID: 214971801
gatewayMessage: A01 - Approved
internalMessage: Approved: 471130 (approval code)
gatewayResult: 00000
AVSMessage:
AVSResponse:
CVMessage:
CVResult:
transactionCode: (null)
transactionDate: 20161020
remainingAmount: $0.00
ISOCountryCode: (null)
ISOCurrencyCode: USD
ISOTransactionDate: 2016-10-20 13:39:46.987
ISORequestDate: 2016-10-20 13:39:46.987
networkReferenceNumber:
merchantCategoryCode:
networkMerchantID: 518564010126944
networkTerminalID: PPB01.
cardType: Visa
maskedPAN: 4***********9269
responseTypeDescription: sale
isCommercialCard: False
streetMatchMessage:
secondsRemaining: (null)
merchantCode: (null)
merchantAccountCode: (null)
merchantName: (null)
receiptTagData: 4F:A0000000031010;95:8080008000;9F10:06010A03A00000;9B:6800;91:;8A:
issuerTagData:
applicationIdentifier: A0000000031010
terminalVerificationResults: 8080008000
issuerApplicationData: 06010A03A00000
transactionStatusInformation: 6800

Sample EMV Sale Receipt

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

BPNPayment.BPNReceipt:
maskedCardNumber: 4***********9269:
chipCardAID: A0000000031010
invoice: 12345
seq: 12345
authorizationCode: 471130
entryMethod: Chip_Read
totalAmount: 6
appLabel: VISA DEBIT
cardHolderName: CARDHOLDER/VALUED
networkMerchantId: 518564010126944
networkTerminalId: PPB01.
cardFirstFour: 4204
cardType: Visa
requiresSignature: YES
pinEntered: NO

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
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
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
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
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
healthCareAmt	Required. The portion of the Total Amount spent on healthcare related services or products. (Format example: 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: 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: DDDD.CC)	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: DDDD.CC)	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: DDDD.CC)	NSDecimalNumber (as indicated) Min Value = 1; Max Value = 50
ClinicAmt	Optional. Indicates the portion of the Healthcare Amount spent on hospitalization. (Format example: DDDD.CC)	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

BPNHealthCare *healthCareFields;

healthCareFields = [[BPNHealthCare alloc] init];

healthCareFields.healthCareAmt = [NSDecimalNumber
decimalNumberWithString:@”3.00”];

healthCareFields.visionAmt = [NSDecimalNumber
decimalNumberWithString:@”2.00”];

healthCareFields.isQualifiedIIAS = @”True”;

_request = [[BPNPaymentRequest alloc]
initInvoiceNumber:@”8888”
pnRefNum:nil
amount:[NSDecimalNumber decimalNumberWithString:@"5.00"]
tipAmount:nil
cashBackAmount:nil
tenderType:TENDER_TYPE_CREDIT
transactionType:TRANSACTION_TYPE_SALE
username:@"emvpgtest"
password:@"57!sE@3Fm"
merchantCode:@"320000"
merchantAccountCode:@"320001"
paymentAccountNumber:nil
token:nil
expirationDate:nil
terminalType:(Valid terminal type here)
industryType:TRANSACTION_INDUSTRY_TYPE_RETAIL
healthCareData:healthCareFields
disableEMV:NO
testMode: YES];

_transaction = [[PayGuardianTransaction alloc] initWithPaymentRequest:_request];
[_transaction runOnCompletion: ^(BPNPayment *payment, NSError *error) {
//process response
} onStateChanged: ^(PayGuardianTransactionState state) {
//process state change
}];

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)

BPNPayment.BridgeCommResponse:
transactionID: 8888
requestType: 004
responseCode: 00000
responseDescription: Successful Request
token: 11110000000373170009
expirationDate: 1218
authorizationCode: 856808
ReferenceNumber:
authorizedAmount: $5.00
originalAmount: $5.00
gatewayTransactionID: 235530604
gatewayMessage: A01 - Approved
internalMessage: Approved: 856808 (approval code)
gatewayResult: 00000
AVSMessage:
AVSResponse:
CVMessage:
CVResult:
transactionCode: 8888
transactionDate: 20171017
remainingAmount: $0.00
ISOCountryCode: 840
ISOCurrencyCode: USD
ISOTransactionDate: 2017-10-17 11:35:04.51
ISORequestDate: 2017-10-17 11:35:04.51
networkReferenceNumber:
merchantCategoryCode:
networkMerchantID:
networkTerminalID:
cardType: Mastercard
maskedPAN: 5***********0009
responseTypeDescription: sale
isCommercialCard: False
streetMatchMessage:
WalletID: (null)
WalletPaymentMethodID: (null)
WalletResponseCode: (null)
WalledREsponseMessage: (null)

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

BPNPayment.BPNReceipt:
maskedCardNumber: 5***********0009
chipCardAID: (null)
invoice: 8888
seq: 8888
authorizationCode: 856808
entryMethod: Swipe_Read
totalAmount: 5.0
appLabel:
cardHolderName: MASTERCARDFSATRACK1AND2
networkMerchantId: 518564010126944
networkTerminalId: PPB01.
cardFirstFour: 0009
cardType: Mastercard
requiresSignature: YES
pinEntered: NO

Hardware

Enable the Barcode Scanner

When a PayGuardian transaction is created, it can be constructed to interact with the Ingenico iSMP barcode scanner. The method enableBarcodeScanner can be used to power on and configure the barcode scanner to accept different barcode symbologies. Once the barcode scanner has been enabled, it will remain active until the iSMP device is powered off/rebooted, or until the disableBarcodeScanner command is called.

Property

Description

Data Type / Min - Max Values

Symbologies

The barcode symbologies to enable. If ‘nil’ or empty, the default symbologies will be enabled.

Default symbologies are 03, 04, 13, 23, 33, and 41. See the table below for descriptions.

NSArray
(Values as listed in Symbologies table below)

Enable Barcode Scanner Request

_request = [[BPNPaymentRequest alloc]
// initialize the request …
_transaction = [[PayGuardianTransaction alloc] initWithPaymentRequest:_request];
[_transaction enableBarcodeScanner:nil];

OR

_request = [[BPNPaymentRequest alloc]
  // initialize the request …
NSArray *symbologies = @[@"03", @"04", @"13", @"23", @"33", @"41"];
_transaction = [[PayGuardianTransaction alloc] initWithPaymentRequest:_request];
[_transaction enableBarcodeScanner:symbologies];

Supported iSMP Symbologies

Value	Symbology
""	Disables all symbologues
"00"	Enables all symbologies
"01"	EAN-13
"02"	EAN-8
"03"	UPC-A
"04"	UPC-E
"08"	UPC-E with addon2
"11"	UPC-A with addon5
"12"	UPC-E with addon5
"13"	Code 39
"15"	Interleaved 2 of 5
"16"	Standard 2 of 5
"17"	Matrix 2 of 5
"19"	Codabar
"21"	MSI
"22"	Plessey
"23"	Code 128
"25"	Code 93
"26"	Code 11
"27"	Telepen
"29"	Code 39 CPI (aka "Italian CPI")
"30"	Codablock A
"31"	Codablock F
"33"	PDF417
"34"	GS1-128
"35"	ISBT128
"36"	Micro PDF
"07"	UPC-A with add2
"37"	GS1 DataBar Omni-Directional
"38"	GS1 DataBar Limited
"39"	GS1 DataBar Expanded
"40"	DataMatrix
"41"	QR Code
"42"	MaxiCode
"74"	AZTEC

Disable the Barcode Scanner

_transaction = [[PayGuardianTransaction alloc] initWithPaymentRequest:_request];
[_transaction disableBarcodeScanner];

Retrieving Barcode Data

When a barcode is scanned, the barcode data and symbology can be retrieved. To do this, the BarcodeScannerDelegate protocol must be implemented. The data can then be handled using the onBarcodeScanned method.

Property	Description	Data Type / Min - Max Values
Data	The scanned barcode data.	NSString
Symbology	The Symbology of the scanned barcode data.	NSString

When the BarcodeScannerDelegate has been implemented, you can set the delegate using setBarcodeDelegate

@interface ViewController () <BarcodeScannerDelegate>
@end

@implementation ViewController

@synthesize_transaction;
@synthesize_request;

-(void) onBarcodeScanned:(NSString*) data
            symbology:(NSString*)symbology {
NSLog(@"Barcode scanned! Symbology ::%@Data::%@", symbology, data);
}

-(void) viewDidLoad {
   _request = [[BPNPaymentRequest alloc]
           // initialize the request ...
_transaction = [[PayGuardianTransaction alloc]
initWithPaymentRequest:_request];
 [_transaction enableBarcodeScanner:nil];
[_transaction setBarcodeDelegate:self];
}

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 accounts will be accepted by the test server's validation mechanism and thus can be used for preliminary testing:

Test Cards

Card Type	Card Brand	Card Number	Expiration Date	Track Data
Credit	Visa	4111111111111111	1017	%B4111111111111111^Smith/John^16041011000 1111A123456789012?
Credit	MasterCard	5499740000000057	1017	%B5499740000000057^Smith/John^16041011000 1111A123456789012?
Credit	Discover	6011000991001201	1017	%B6011000991001201^Smith/John^16041011000 1111A123456789012?
Credit	Amex	4111111111111111	1017	%B371449635392376^Smith/John^16041011000 1111A123456789012?
Debit	Visa	4217651111111119	1017	%B4217651111111119^Smith/John^16041011234567 440?;4217651111111119=16041011234567440?
Debit	MasterCard	5149612222222229	1017	%B5149612222222229^Smith/John^16041011234567 440?;5149612222222229=16041011234567440?

Encrypted Data

Card Number	Expiration Date	Secure Format	MSRKSN	Track 1 Encrypted	Track 2 Encrypted
5526399000648568	0416	SecureMagV2	310601012B000B40007B	BD12FA1B13FB19BD88 97CBCF4109205B6913 3A78F2B2181F2D3849 B484303F4CEB54FD28 57748B0D92E72E0BAF B9D9876C431FF24F37 12866550DA1D697E84F 353F3EEBB8AA42E4F	67E98B7924544F5 803BC4A4453834B D13D1929CD70063 60A551A189038301 1EBBEDBB3442BD7 1F45
4012000033330026	0416	SecureMagV2	310601012B000B400080	AA06168B0C7DFBF22D FEC13D7B49242906D26 39C65E4AAF5364B143E D5DCB9F45AA04BA73F 631032B83648311E88E4 ED921451F0E9684E866 613F35BD74F53802C3A A9E56643863E988DD4B ABD4753A5	D011E8820440DE01C D626AE55921ADA5F3 D475EB9150E2959DF A1EE6353A3204EF7F 69797B97D753
5473500000000014	1225	SecureMag	91070100000000800007	EA02EB27DAFC3BE1AE 43C318D96F39E9AB90D 55B0978614D7860C8957 21DD0E9EA358FDDCA4 A0FAADE3D1E0E69D91 FCB31B70E73B8FB5E49 F4E4AF6219AB9B6F75C FFF8A6385DE6645426E C7E9DDD128C7D63E66 2B2C6E969E3CEE75789 F66C48251B69A6B9C79 CDC570FD984867ACA2
4012002000060016	1225	SecureMag	91070100000000800008	C14C88046A89D221FA5 0EF0DE61B61C4C11309 5BB6FB2D6185BC5100A BB0ABF6DDA5F7D1F4F 3DFA16DFB365EA098C C927195B4A3F9762BF8 5262D1530C88181B794 E3CADBEA469539DEBB D341751599322B1A7A4 D2C760044CCC2B311B 4D175959FCE0E2DF9B0 BB7

Test Amount Ranges

As a part of the testing, the amount ranges specified below, can be used to trigger specific response codes from the server. Any valid account number and any properly formatted billing address can be used for the test.

Sales and Authorizations

Amount Range		Credit Cards
In dollars	In Cents	Response Message
5.00 – 69.99	500 – 6999	Approved.
70.00 – 79.99	7000 – 7999	Invalid Card Number (Invalid Account Number)
80.00 – 89.99	8000 – 8999	Card reported lost/stolen (Lost/Stolen Card)
90.00 – 99.99	9000 – 9999	Call for Authorization (Referral)*
100.00 – 109.99	10000 – 10999	Hold – Pick up card (Pick Up Card)
110.00 – 119.99	11000 – 11999	CSC is invalid (Decline CSC/CID Fail)
120.00 – 129.99	12000 – 12999	Insufficient Funds
130.00 – 139.99	13000 – 13999	Processing Network Unavailable
140.00 – 149.99	14000 – 14999	Processing Network Error
150.00 – 159.99	15000 – 15999	Partially Approved**

*This range is designated to test voice authorization. Sale, Auth request in the amount between $90.00 – 99.99 will Response in a decline code, however if approval code 012345 is specified, then an approval will be received

**This range is designated to test partial authorizations. By setting Sale with this amount range the partially approved transaction will be received. Approved amount will be $10 less than the originally requested amount.

Credits

Property	Description	Data Type / Min - Max Values
5.00 – 69.99	500 - 6999	Credit Posted

More Information

Table of Contents