iOS Methods/Models/Delegates
Models
PsBluetoothDevice (BBPOS Only)
Property | Type | Description |
---|---|---|
Serial Number | NSString | Serial number of BBPOS device. |
Manufacturer | NSString | Manufacturer of device. |
Model | NSString | Model of device. |
PsDeviceInfo
Property | Type | Description |
---|---|---|
Device Description | NSString | Description of device. |
Serial Number | NSString | Serial number of BBPOS device. |
Firmware Version | NSString | Device Firmware version. |
Configuration Version | NSString | Description config version. |
Battery Percentage | NSString | Battery percentage of device. |
Battery Level | NSString | Battery level of device. |
PsSaleRequest
Property | Type | Description |
---|---|---|
Amount | NSDecimalNumber | Required. Min=0.01 Max=2000000.00 Amount to charge of currency. Must be a positive number. |
Duplicate Check | NSString | Optional. Default:"enabled" Valid values: "enabled", "disabled". Indicates the duplicate check mode. |
Currency | NSString | Optional. Default:"usd". Type of currency to be collected. Only USD supported at this time (default). |
External Id | NSString | Optional. <= 50 characters. Unique identifier for the payment in merchant or partner's system. |
Card Sale Description | NSString | Optional. <= 5000 characters. Text field reserved for partner/merchant use. |
Capture | NSString | IDYNAMO ONLY Optional. Possible values: "completed_sale" "auth_until_capture" "tip_adjustment". 'completed_sale' (default) will authorize and capture the sale at the specified amount. 'auth_until_capture' requires the capture endpoint for the payment to be added to a settlement batch. 'tip_adjustment' allows for the tip_adjustment endpoint to be called up until just prior to the batch close time. |
Allow Partial Approvals | BOOL | Optional. Default:FALSE. If true, allows partial approvals. Most useful for gift cards with limited funds. |
PsSaleResponse
Property | Type | Description |
---|---|---|
Transaction Id | NSString | Unique Id of transaction. |
Acquirer Message | NSString | Host error message returned on failure or decline. Do not base application logic on this message as it may change without notice. |
Authorization Code | NSString | Acquirer authorization code. |
Approved Amount | NSDecimalNumber | Amount approved on a partial approval |
Batch Id | NSNumber | Settlement batch id (card only). |
Card | PsCardData | Card response |
Outcome | PsSaleOutcome | Sale outcome |
Emv | PsEmvResponse | EMV response data if present |
PsSaleOutcome
Property | Type | Description |
---|---|---|
Result | NSString | Result of transaction request. Valid values: "success", "failed", "declined" |
Code | NSString | 4-digit PaySimple result code. The code will not change, so it's safe to create code logic reacting to a specific failure code. Code 1000 indicates success. |
Outcome Description | NSString | Description of decline, failure or success. This is in human-readable format, so it is a good practice to display this text to the user in your interface. Don't base logic in your code on this text, as it may change from time to time. |
PsCardData
Property | Type | Description |
---|---|---|
Card Brand | NSString | Card brand type. Valid values: "unknown", "visa", "mastercard", "amex", "discover" |
Last 4 | NSString | Last 4 digits of card number. |
Expiration Month | NSNumber | Month of card expiration. |
Expiration Year | NSNumber | Year of card expiration in 4 digit format. |
PsEmvResponseData
Property | Type | Description |
---|---|---|
Application Identifier | NSString | Application Identifier. |
Application Preferred Name | NSString | Application Preferred Name. |
Application Label | NSString | Application Label. |
Cryptogram | NSString | Cryptogram value. |
Host Response Code | NSString | Host Response Code. |
Host Response Message | NSString | Host Response Message. |
EMV Receipt Requirements
THE FOLLOWING ARE REQUIRED FOR EMV RECEIPTS
Application Identifier (AID) of the application used.
Application Preferred Name (if available and supported) or Application Label
Cryptogram type/value
Host Response Code/Host Response Message (e.g. 00/AP, etc)
Host Response Message
Methods
Initialize SDK - Class Method
Initializes the SDK and returns TRUE if initialization occurred without error. This method should only need to be called once while the app is running.
+ (BOOL)initializeSdk:(PsSDKDeviceType)device
environment:(NSString *)env
error:(NSError **)error;
Property | Type | Description |
---|---|---|
device | PsSDKDeviceType | Required. Uniquely identifies device type. Possible values: IDYNAMO or BBPOS |
environment | NSString | Required. Environment to use. Possible values: "SBX" for sandbox or "PROD" for production |
error | NSError | Required. NSError reference to use in case of initialization failure |
Example Implementation:
if([PsSDK initializeSdk:IDYNAMO environment:@"SBX" error:&error])
{
self.sharedPsSDK = [PsSDK sharedInstance];
self.sharedPsSDK.delegate = self;
}
else
{
// Handle error here
}
Re-Initialize SDK - Class Method
Sets the shared instance to nil to allow the SDK to reinitialized with a different device type or environment. You must first disconnect the current device associated with the shared instance.
+ (void)resetSdk
Disconnect current device first
The code sample below includes disconnecting the current device first which must be done before resetting the SDK.
Example Implementation:
-(void) resetSDK
{
void (^completionCallback)(BOOL, NSError *) = ^(BOOL didDisconnect, NSError *myError)
{
if (didDisconnect) {
// Do disconnect dialogues here.
[PsSDK resetSdk];
} else {
// Handle disconnect failure
}
};
if (_sharedPsSDK != nil) {
[_sharedPsSDK disconnectDeviceWithHandler:completionCallback];
}
}
SharedInstance - Class Method
Returns a shared instance of the PsSDK service.
+ (PsSDK *)sharedInstance;
Example Implementation:
- (void)viewDidLoad
{
[super viewDidLoad];
self.sharedPsSDK = [PsSDK sharedInstance];
}
IsInitialized - Class Method
Returns BOOL to indicate if the SDK has been initialized and a shared instance exists.
+ (BOOL)isInitialized;
Example Implementation:
if ([PsSDK isInitialized])
{
// Do logic based code here
}
Scan for Bluetooth enabled devices (BBPOS only) - Instance Method
Optional for BBPOS device. Will scan for all powered on BBPOS devices within range of the iOS device. Executes completion handler once scan is complete (2 - 5 seconds). Allows for connecting to a specific BBPOS device when multiple devices are present. Can associate returned serial numbers with devices and send a specific serial number to connect to in ConnectDeviceWithClientToken. Requires a client token in order to initiate the scan for devices that are enabled for your client/merchant key.
- (void) scanForBluetoothDevicesWithClientToken:(NSString *)clientToken
completionHandler: (void(^)(NSArray<PsBluetoothDevice *> *, NSError *error))handler
Property | Type | Description |
---|---|---|
clientToken | NSString | Required. PaySimple Client token that is needed to connect to the BBPOS device |
completionHandler | Code Block | Required. Upon execution passes back a an NSArray of PsBluetoothDevice Also takes NSError reference to pass back error information in case of connection failure |
Example Implementation:
void (^btScanCallback)(NSArray<PsBluetoothDevice *> *, NSError *error) = ^(NSArray<PsBluetoothDevice *> *deviceArray, NSError *myerror)
{
if (deviceArray.count > 0) {
// Handle connection logic here. Choose a serial number to connect to.
});
} else {
// Handle error or no devices found here
}
};
// Do client token request prior to calling this method. Suggest placing this method inside client token callback or delegate.
[_sharedPsSDK connectDeviceWithClientToken:myClientToken
completionHandler:completionCallback];
ConnectDeviceWithClientToken - Instance Method
Required for BBPOS device. Connects to the card reader device. Not required for iDynamo or Rambler implementation. Executes completion handler once connected. Getting a new client token prior to calling this method is strongly recommended to avoid token validation/expiration issues.
- (void) connectDeviceWithClientToken:(NSString *)clientToken
serialNumber:deviceToConnect
completionHandler: (void(^)(BOOL didConnect, PsDeviceInfo *deviceInfo, NSError *error))handler;
Property | Type | Description |
---|---|---|
clientToken | NSString | Required. PaySimple Client token that is needed to connect to the BBPOS device |
serialNumber | NSString | Optional. Serial number of device to connect to (eg. @"CHB204839000034"). Can be null or empty string. Will connect to previously connected BBPOS |
completionHandler | Code Block | Required. Upon execution passes back a BOOL to indicate if device successfully connected. Returns device info of connected device. Also takes NSError reference to pass back error information in case of connection failure |
Example Implementation:
void (^completionCallback)(BOOL, PsDeviceInfo *, NSError *) = ^(BOOL isConnected, PsDeviceInfo *deviceInfo, NSError *connectionError)
{
if (!isConnected) {
// Handle error here
});
} else {
// Do successful connection logic based code here
}
};
// Do client token request prior to calling this method. Suggest placing this method inside client token callback or delegate.
[_sharedPsSDK connectDeviceWithClientToken:myClientToken
completionHandler:completionCallback];
ConnectDeviceWithHandler - Instance Method
Connects to the card reader device. Not supported for BBPOS. Optional for iDynamo since MakeSale will make the connection for you. Executes completion handler once connected.
- (void) connectDeviceWithHandler: (void(^)(BOOL didConnect, PsDeviceInfo *deviceInfo, NSError *error))handler;
Property | Type | Description |
---|---|---|
completionHandler | Code Block | Required. Upon execution passes back a BOOL to indicate if device successfully connected. Returns device info of connected device. Also takes NSError reference to pass back error information in case of connection failure |
Example Implementation:
void (^completionCallback)(BOOL, PsDeviceInfo *, NSError *) = ^(BOOL isConnected, PsDeviceInfo *deviceInfo, NSError *connectionError)
{
if (!isConnected) {
// Handle error here
});
} else {
// Do successful connection logic based code here
}
};
[_sharedPsSDK connectDeviceWithHandler:completionCallback];
DisconnectDeviceWithHandler - Instance Method
Disconnects the device. Not explicitly needed in most situations but can be used to disconnect the device after a sale is made if you need to do some disconnect based logic in your app or to prevent any further swipe data being read.
- (void) disconnectDeviceWithHandler: (void(^)(BOOL didDisconnect, NSError *error)) handler;
Property | Type | Description |
---|---|---|
handler | Code Block | Required. Upon execution passes back a BOOL to indicate if device successfully disconnected. Also takes NSError reference to pass back error information in case of disconnection failure |
Example Implementation:
void (^completionCallback)(BOOL, NSError *) = ^(BOOL didDisconnect, NSError *disconnectError)
{
if (!didDisconnect) {
// Handle error here
} else {
// Do disconnect logic based code here
}
};
[_sharedPsSDK disconnectDeviceWithHandler:completionCallback];
IsDeviceConnected - Instance Method
Returns BOOL to indicate if the device is connected or not.
+ (BOOL)isDeviceConnected;
Example Implementation:
if ([_sharedPsSDK isDeviceConnected])
{
// Do logic based code here
}
GetDeviceName - Instance Method
Returns NSString of the attached device name. Returns nil if no device is connected. Possible values: "iDynamo", "BBPOS"
- (NSString *)getDeviceName;
Example Implementation:
NSString *displayName = [self.sharedPsSDK getDeviceName];
GetDeviceBatteryPercentage - Instance Method
Returns NSString of the attached device battery percentage. Returns nil if no device is connected. Possible values: "99", "50" etc
- (NSString *)getDeviceBatteryPercentage;
Example Implementation:
NSString *displayName = [self.sharedPsSDK getDeviceName];
MakeSaleWithClientToken - Instance Method
Makes a sale using a PaySimple Client token, a PsSaleRequest object and a completion handler. Getting a new Client token prior to calling this method is strongly recommended to avoid token validation/expiration issues. For iDynamo this method will automatically attempt to connect to the iDynamo device so explicit separate connection logic is not needed. If no connection can be made to the iDynamo device and error will be returned to allow for retry logic in your implementation.
- (void) makeSaleWithClientToken:(NSString *)clientToken
request:(PsSaleRequest *)saleRequest
completionHandler:(void(^)(PsSaleResponse *response, NSError *error))handler;
Property | Type | Description |
---|---|---|
clientToken | NSString | Required. PaySimple Client token that is needed to make a sale |
completionHandler | Code Block | Required. Upon execution passes back a PsSaleResponse object containing relevant sale result data. Also takes NSError reference to pass back error information in case of error in the sale flow |
Example Implementation:
NSDecimalNumber *amount = [NSDecimalNumber decimalNumberWithString:self.amountField.text];
PsSaleRequest *saleRequest = [[PsSaleRequest alloc]initWithamount:amount
duplicateCheck:@"enabled"
currency:@"usd"
externalId:@"myUniqueId"
cardSaleDescription:@"saleDescription"
capture:@"completed_sale"
allowPartialApprovals:YES;
void (^completionCallback)(PsSaleResponse *response, NSError *) = ^(PsSaleResponse *response, NSError *saleError)
{
if (saleError == nil) {
// Handle success here
});
} else {
// Handle error here
}
};
// Do [Client token](https://documentation.paysimple.com/v2019/docs/authorization#section-client-token-authorization) request prior to calling this method. Suggest placing this method inside client token callback or delegate.
[sharedPsSDK makeSaleWithClientToken:clientToken
request:saleRequest
completionHandler:completionCallback];
StopCurrentBbposFlow - Instance Method
Call this method to stop the current BBPOS sale flow if it has already been started. For example you have prompted the customer to insert, swipe or chip read card. This is stop the sale flow connection with the BBPOS device and reset it to an idle state.
- (void)stopCurrentBbposFlow;
Example Implementation:
[self.sharedPsSDK stopCurrentBbposFlow];
Delegates
deviceConnectionDidChange - Optional delegate
Delegate fires when the connection status if the device changes.
- (void)deviceConnectionDidChange:(NSString *)deviceType
isConnected:(BOOL)isConnected;
Property | Type | Description |
---|---|---|
deviceType | NSString | Valid values: "iDynamo", "BBPOS" |
isConnected | Bool | Indicates if the device is connected or not |
Example Implementation:
-(void) deviceConnectionDidChange:(NSString *)deviceType
isConnected:(BOOL)isConnected
{
NSLog(@"DeviceConnectionDidChange Delegate Triggered");
if (!isConnected)
{
dispatch_async(dispatch_get_main_queue(), ^{
UIAlertController* alertController = [UIAlertController
alertControllerWithTitle:@"Device is not connected"
message:@"You must connect device to make sale"
preferredStyle:UIAlertControllerStyleAlert];
UIAlertAction* alertAction = [UIAlertAction
actionWithTitle:@"OK"
style:UIAlertActionStyleDefault
handler:^(UIAlertAction* action){}];
[alertController addAction:alertAction];
[self presentViewController:alertController animated:YES completion:nil];
});
}
}
onBbposDisplayText - Optional delegate
Delegate fires when the BBPOS device has text to display to the user such as prompts. Examples include "Insert, Swipe or Tap Card", "Remove Card", "Thank you" etc.
-(void) onBbposDisplayText:(NSString *)text;
Property | Type | Description |
---|---|---|
displayText | NSString | "Insert, Swipe or Tap Card", "Remove Card", "Thank you" etc. |
Example Implementation:
-(void) onBbposDisplayText:(NSString *)text
{
UIAlertController *alertController = [UIAlertController alertControllerWithTitle: text message: @"" preferredStyle: UIAlertControllerStyleAlert];
UIAlertAction *alertAction = [UIAlertAction actionWithTitle: @"Cancel"
style: UIAlertActionStyleDefault
handler: ^(UIAlertAction * action)
{
[sharedPsSDK stopCurrentBbposFlow];
}
];
[alertController addAction: alertAction];
[weakSelf presentViewController: alertController animated: NO completion: nil];
}
onBbposRemoveCard - Optional delegate
Delegate fires when the BBPOS device detects that the card has been removed. Should stop current BBPOS sale flow if this delegate fires.
-(void) onBbposRemoveCard;
Example Implementation:
-(void) onBbposRemoveCard
{
UIAlertController *alertController = [UIAlertController alertControllerWithTitle: "Remove Card" message: @"" preferredStyle: UIAlertControllerStyleAlert];
UIAlertAction *alertAction = [UIAlertAction actionWithTitle: @"Cancel"
style: UIAlertActionStyleDefault
handler: ^(UIAlertAction * action)
{
[sharedPsSDK stopCurrentBbposFlow];
}
];
[alertController addAction: alertAction];
[weakSelf presentViewController: alertController animated: NO completion: nil];
}
onBbposDeviceInitializationProgress - Optional delegate
Delegate fires when the BBPOS device pairs with the phone or tablet. Will repeatedly fire until device pairs. First time device pairs to BBPOS, BBPOS must be at least 50% charged.
- (void)onBbposDeviceInitializationProgress:(double)currentProgress
description:(NSString *)description
model:(NSString *)model
serialNumber:(NSString *)serialNumber;
Example Implementation:
-(void) onBbposDeviceInitializationProgress:(double)currentProgress
description:(NSString *)description
model:(NSString *)model
serialNumber:(NSString *)serialNumber
{
NSNumber *progress = [NSNumber numberWithDouble:currentProgress];
// Check for presented alert view controller. If exists, just update
UIAlertController *alertController = [UIAlertController alertControllerWithTitle: "Pairing Progress" message: [progress stringValue] preferredStyle: UIAlertControllerStyleAlert];
UIAlertAction *alertAction = [UIAlertAction actionWithTitle: @"Cancel"
style: UIAlertActionStyleDefault
handler: ^(UIAlertAction * action)
{
[sharedPsSDK stopCurrentBbposFlow];
}
];
[alertController addAction: alertAction];
[weakSelf presentViewController: alertController animated: NO completion: nil];
}
onBbposBatteryLow - Optional delegate
Delegate fires when the BBPOS device battery level is low
-(void) onBbposBatteryLow;
Example Implementation:
-(void) onBbposBatteryLow
{
UIAlertController *alertController = [UIAlertController alertControllerWithTitle: "Low Battery Warning" message: @"" preferredStyle: UIAlertControllerStyleAlert];
UIAlertAction *alertAction = [UIAlertAction actionWithTitle: @"Cancel"
style: UIAlertActionStyleDefault
handler: ^(UIAlertAction * action)
{
[sharedPsSDK stopCurrentBbposFlow];
}
];
[alertController addAction: alertAction];
[weakSelf presentViewController: alertController animated: NO completion: nil];
}
onBbposDidDisconnect - Optional delegate
Delegate fires when the BBPOS device disconnects
-(void) onBbposDidDisconnect;
Example Implementation:
-(void) onBbposDidDisconnect
{
UIAlertController *alertController = [UIAlertController alertControllerWithTitle: "Device did disconnect" message: @"" preferredStyle: UIAlertControllerStyleAlert];
UIAlertAction *alertAction = [UIAlertAction actionWithTitle: @"Ok"
style: UIAlertActionStyleDefault
handler: ^(UIAlertAction * action)
{
[sharedPsSDK stopCurrentBbposFlow];
}
];
[alertController addAction: alertAction];
[weakSelf presentViewController: alertController animated: NO completion: nil];
}
onBbposDidError - Optional delegate
Delegate fires when the BBPOS device returns an error that is device related and not sale related.
-(void) onBbposDidError:(NSError *)error
Example Implementation:
-(void) onBbposDidError
{
UIAlertController *alertController = [UIAlertController alertControllerWithTitle: "BBPOS Device Error" message: error.description preferredStyle: UIAlertControllerStyleAlert];
UIAlertAction *alertAction = [UIAlertAction actionWithTitle: @"Ok"
style: UIAlertActionStyleDefault
handler: ^(UIAlertAction * action)
{
[sharedPsSDK stopCurrentBbposFlow];
}
];
[alertController addAction: alertAction];
[weakSelf presentViewController: alertController animated: NO completion: nil];
}
Updated about 2 months ago