Versions Compared
Key
- This line was added.
- This line was removed.
- Formatting was changed.
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.
Code Block | ||
---|---|---|
| ||
- (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.
Code Block | ||
---|---|---|
| ||
- (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
Code Block | ||
---|---|---|
| ||
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: https://www.bridgepaynetsecuretest.com/paymentservice/requesthandler.svc | URL String |
Code Block |
---|
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:
Code Block |
---|
_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:
Code Block |
---|
initWithPaymentRequest:(BPNPaymentRequest *)request; |
The run method with completion is:
Code Block | ||
---|---|---|
| ||
- (void) runOnCompletion:(void (^)(BPNPayment *payment, NSError *error)) onCompletion onStateChanged:(void (^)(PayGuardianTransactionState state)) onStateChanged onReaderStateChanged:(void (^)(PayGuardianReaderState readerState)) onReaderStateChanged onCardDataAvailable:(void (^)(NSString *cardIdentifier)) onCardDataAvailable; |
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 |
---|---|---|
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 |
RequestType | Returns the 3 digit value for the type of BridgeComm request message submitted. Valid values are: | NSString |
ResponseCode | BridgeCommResponseCodeSuccess = 0 | Enum |
ResponseDescription | Plain text response message. | NSString |
Token | Unique token assigned to a transaction. | NSString |
ExpirationDate | Card expiration date. | NSString |
AuthorizationCode | Authorization code for a transaction. | NSString |
OriginalReferenceNumber | Original reference number from a request. | NSString |
AuthorizedAmount | Amount authorized by the processor. | NSDecimalNumber |
OriginalAmount | Original requested amount of the transaction. | NSDecimalNumber |
GatewayTransactionID | Unique ID of a transaction in the gateway. | NSString |
GatewayMessage | Details from the processor or payment gateway regarding the transaction result. | NSString |
InternalMessage | Internal Message from the gateway. | NSString |
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 |
ISOCountryCode | Country code for currency. | NSString |
ISOCurrencyCode | Currency code for a transaction. | NSString |
ISOTransactionDate | Date of transaction from the processor. | NSString |
ISORequestDate | Date of request at a processor. | NSString |
NetworkReferenceNumber | Unique ID of a transaction at the processor. | NSString |
NetworkCategoryCode | Processor specific category code. | NSString |
NetworkMerchantId | Merchant ID from the gateway. | NSString |
NetworkTerminalId | Network terminal ID from the gateway. | NSString |
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 |
MerchantAccountCode | Gateway merchant account code used in a transaction. | NSString |
MerchantName | Name of a merchant. | NSString |
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 |
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 |
EntryMethod | Card number entry method. | NSString |
TotalAmount | Total amount of the transaction. | NSDecimalNumber |
AppLabel | Name of application | NSString |
CardHolderName | Name on the card | NSString |
NetworkMerchantID | Merchant ID. Dependent on processor. | NSString |
NetworkTerminalID | Terminal ID. Dependent on processor. | NSString |
CardFirstFour | First four digits of a card | NSString |
CardType | Type of card | NSString |
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.
Code Block |
---|
_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 transaction state change } onReaderStateChanged: ^(PayGuardianReaderState state) { //process reader state change onCardDataAvailable:^(NSString *cardIdentifier) { // optional, indicates that a BIN lookup has been performed }]; |
MSR Sale Type Response
An example of a basic MSR sale transaction response.
Code Block |
---|
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.
Code Block |
---|
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.
Code Block |
---|
_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.
Code Block |
---|
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
Code Block |
---|
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.
Code Block |
---|
_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.
Code Block |
---|
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.
Code Block |
---|
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.
Code Block |
---|
_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.
Code Block |
---|
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.
Code Block |
---|
_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.
Code Block |
---|
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.
Code Block |
---|
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.
Code Block |
---|
_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.
Code Block |
---|
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.
Code Block |
---|
_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.
Code Block |
---|
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.
Code Block |
---|
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.
Code Block |
---|
_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.
Code Block |
---|
_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.
Code Block |
---|
_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.
Code Block |
---|
_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.
Code Block |
---|
_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
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
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
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
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
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.
Code Block |
---|
_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.
Code Block |
---|
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.
Code Block |
---|
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: http://DDDD.CC ) | NSDecimalNumber (as indicated) |
transmitAmt | Optional. Indicates the portion of the total amount spent on healthcare-related transportation. (Format example: http://DDDD.CC ) | NSDecimalNumber (as indicated) |
prescriptionAmt | Optional. Indicates the portion of the Healthcare Amount spent on prescription drugs or products. (Format example: http://DDDD.CC ) | NSDecimalNumber (as indicated) |
VisionAmt | Optional. Indicates the portion of the Healthcare Amount spent on vision related medical services. (Format example: http://DDDD.CC ) | NSDecimalNumber (as indicated) |
DentalAmt | Optional. Indicates the portion of the Healthcare Amount spent on dental related medical services. (Format example: http://DDDD.CC ) | NSDecimalNumber (as indicated) |
ClinicAmt | Optional. Indicates the portion of the Healthcare Amount spent on hospitalization. (Format example: http://DDDD.CC ) | NSDecimalNumber (as indicated) |
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 |
Examples
Sale Type Request using HealthCare Data
An example of a basic sale transaction request with healthcare elements
Code Block |
---|
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)
Code Block |
---|
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).
Code Block |
---|
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 |
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 Credit Card and ACH Account Numbers
Test Amount Ranges
The following page provides information on test amount ranges Test Dollar Amount Ranges
More Information
Page Tree | ||||||
---|---|---|---|---|---|---|
|
Table of Contents
Table of Contents |
---|