iOS Methods/Models/Delegates

Models

PsBluetoothDevice (BBPOS Only)

PropertyTypeDescription
Serial NumberNSStringSerial number of BBPOS device.
ManufacturerNSStringManufacturer of device.
ModelNSStringModel of device.

PsDeviceInfo

PropertyTypeDescription
Device DescriptionNSStringDescription of device.
Serial NumberNSStringSerial number of BBPOS device.
Firmware VersionNSStringDevice Firmware version.
Configuration VersionNSStringDescription config version.
Battery PercentageNSStringBattery percentage of device.
Battery LevelNSStringBattery level of device.

PsSaleRequest

PropertyTypeDescription
AmountNSDecimalNumberRequired. Min=0.01 Max=2000000.00 Amount to charge of currency. Must be a positive number.
Duplicate CheckNSStringOptional. Default:"enabled" Valid values: "enabled", "disabled". Indicates the duplicate check mode.
CurrencyNSStringOptional. Default:"usd". Type of currency to be collected. Only USD supported at this time (default).
External IdNSStringOptional. <= 50 characters. Unique identifier for the payment in merchant or partner's system.
Card Sale DescriptionNSStringOptional. <= 5000 characters. Text field reserved for partner/merchant use.
CaptureNSStringIDYNAMO 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 ApprovalsBOOLOptional. Default:FALSE. If true, allows partial approvals. Most useful for gift cards with limited funds.

PsSaleResponse

PropertyTypeDescription
Transaction IdNSStringUnique Id of transaction.
Acquirer MessageNSStringHost error message returned on failure or decline. Do not base application logic on this message as it may change without notice.
Authorization CodeNSStringAcquirer authorization code.
Approved AmountNSDecimalNumberAmount approved on a partial approval
Batch IdNSNumberSettlement batch id (card only).
CardPsCardDataCard response
OutcomePsSaleOutcomeSale outcome
EmvPsEmvResponseEMV response data if present

PsSaleOutcome

PropertyTypeDescription
ResultNSStringResult of transaction request. Valid values: "success", "failed", "declined"
CodeNSString4-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 DescriptionNSStringDescription 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

PropertyTypeDescription
Card BrandNSStringCard brand type. Valid values: "unknown", "visa", "mastercard", "amex", "discover"
Last 4NSStringLast 4 digits of card number.
Expiration MonthNSNumberMonth of card expiration.
Expiration YearNSNumberYear of card expiration in 4 digit format.

PsEmvResponseData

PropertyTypeDescription
Application IdentifierNSStringApplication Identifier.
Application Preferred NameNSStringApplication Preferred Name.
Application LabelNSStringApplication Label.
CryptogramNSStringCryptogram value.
Host Response CodeNSStringHost Response Code.
Host Response MessageNSStringHost 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;
PropertyTypeDescription
devicePsSDKDeviceTypeRequired. Uniquely identifies device type. Possible values: IDYNAMO or BBPOS
environmentNSStringRequired. Environment to use. Possible values: "SBX" for sandbox or "PROD" for production
errorNSErrorRequired. 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
PropertyTypeDescription
clientTokenNSStringRequired. PaySimple Client token that is needed to connect to the BBPOS device
completionHandlerCode BlockRequired. 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;
PropertyTypeDescription
clientTokenNSStringRequired. PaySimple Client token that is needed to connect to the BBPOS device
serialNumberNSStringOptional. Serial number of device to connect to (eg. @"CHB204839000034"). Can be null or empty string. Will connect to previously connected BBPOS
completionHandlerCode BlockRequired. 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. 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;
PropertyTypeDescription
completionHandlerCode BlockRequired. 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;
PropertyTypeDescription
handlerCode BlockRequired. 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;
PropertyTypeDescription
clientTokenNSStringRequired. PaySimple Client token that is needed to make a sale
completionHandlerCode BlockRequired. 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;
PropertyTypeDescription
deviceTypeNSStringValid values: "iDynamo", "BBPOS"
isConnectedBoolIndicates 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;
PropertyTypeDescription
displayTextNSString"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];    
}