|id_number||NSString||Id (serial) number of device.|
|manufacturer||NSString||Manufacturer/brand of device.|
|model||NSString||Model of device.|
|battery_percentage||NSString||Battery percentage of device between 0-100%.|
|amount||NSNumber||Required. Amount to charge. Must be a positive number.|
|paymentDescription||NSString||Optional. A string to be displayed on your customer’s credit card statement. This may be up to 22 characters. The statement descriptor must contain at least one letter, may not include \<>"' characters, and will appear on your customer’s statement in capital letters. Non-ASCII characters are automatically stripped. While most banks and card issuers display this information consistently, some may display it incorrectly or not at all.|
|paymentDescriptionSuffix||NSString||Optional. A string to specify details about the transaction so your customer can understand it clearly on their statement. The suffix is concatenated with the statementDescriptor, the \* symbol, and a space to form the complete statement descriptor that your customer sees. Maximum 22 characters for the final concatenated descriptor.|
|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.|
|duplicate_check||NSString||**WORLDPAY/EXPRESS ONLY** Optional. Default:"enabled" Valid values: "enabled", "disabled". Indicates the duplicate check mode.|
|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||**WORLDPAY/EXPRESS ONLY** Optional. Default: FALSE. If true, allows partial approvals. Most useful for gift cards with limited funds.|
Constants to be used to help consumers specify which events they would like to listen to when calling **Initalize Sdk**.
These string values will be accessible through the ECPSdkEventsConstants class. An example below shows creating a sample set of Events utilizing ECPSdkEventConstants.
|transaction_id||NSString||Unique Id of transaction.|
|acqurier_message||NSString||Acquirer message returned. Do not base application logic on this message as it may change without notice.|
|authorization_code||NSString||Acquirer Authorization code.|
|batch_id||NSNumber||Settlement batch id (card only). **Value will be nil for Stripe processed payments.**|
|emv||ECPEmvData||EMV response data if present|
|entry_mode||NSString||Entry mode of transaction|
|result||NSString||Result of transaction request. Valid values "success", "failed", "declined"|
|code||NSString||4-digit PaySimple result code.|
|outcome_description||NSDecimalNumber||Description of decline, failure or success.|
|card_brand||NSString||Card brand type.|
|last4||NSString||Last 4 digits of card number.|
|card_holder_name||NSString||Name of cardholder|
|expiration_month||NSNumber||Month of card expiration|
|expiration_year||NSNumber||Year of card expiration in 4 digit format.|
|application_preferred_name||NSString||Application Preferred Name.|
|application_label||NSString||Application Label. **Value will be nil for Stripe payments.**|
|authorization_response_code||NSString||Authorization Response Code.|
|authorization_response_message||NSString||Authorization Response Message.|
|is_pin_verified||BOOL||Whether or not the result is pin verified.|
# Client Token Block
Authorization via Client Token is required to use this SDK. In this SDK, we have introduced the concept of a Client Token Block which consumers will pass in to the **Initialize Sdk** method in order to ensure the SDK is able to associate and authenticate with the proper merchant/client.
Before integrating to our SDK, you should create an endpoint on your secure backend server which returns the proper PaySimple client token for a particular PaySimple user that you are trying to use this SDK with. How you map your application's users to a PaySimple user is up to you in your backend - you just need to be sure to use this Client Token Block to get a proper PaySimple token tied to the user you would like to utilize the SDK for each time you initialize. The type of authorization token currently supported will be <https://documentation.paysimple.com/v2019/docs/authorization#client-token-authorization-rarely-used> .
The client token code block you provide will then be called by our SDK as needed during various actions which require PaySimple authorization.
Here is a mock implementation of a Client Token Block to help get you started. **Notice how in the failure flows for getting the token, completion handler is called with nil and an error. When you successfully fetch the token, the completion handler should be called with the token and a nil error.**
## Client Token Authorization Example
After defining this client token block, you can then pass it into the Initialize SDK method. See below a sample call, on how we access this userClientTokenBlock variable which was created.
# Class Methods
## Shared Instance
Returns a shared instance of the ECPSdk service. If you would like, you can store this in a variable to later be accessed by your class.
# Instance Methods
As best practice, make sure the completion handler of one operation within the ECPSdk is called prior to attempting to execute an additional operation, to avoid unintended behavior.
## Initialize SDK
Initializes the SDK. Provides a completion handler to determine the result of the SDK initialization. Returns YES if initialization occurred without error. Consumers must initialize the SDK prior to any other SDK actions. User must pass in environment, list of events they would like to subscribe to, and a **Client Token Block**
|environment||NSString||Required. Environment to use. Possible values: "SBX" for sandbox or "PROD" for production|
|subscribedEvents||NSSet||Set of events consumer would like to listen to. If a nil or empty set is passed in, by default user will subscribe to all events. ECPSdkEventConstants.ALL will also subscribe to all events, if it is present in the NSSet. If you only want to listen to specific events, please specify those events using ECPSdkEventConstants. For example, if you only wanted to listen to ECPDeviceMessageEvent and ECPConnectionChangedEvent, you would pass in a set as that has been initialized as follows: NSSet \*events = [NSSet setWithObjects: ECPSdkEventConstants.ECPDeviceMessageEvent, ECPSdkEventConstants.ECPConnectionChangedEvent, nil];|
|clientTokenBlock||Code Block||Required. Code block which returns a PaySimple client token and an error so the SDK can hook into your client/merchant. For more info and sample code block implementations, see the **Client Token Block** section.|
|completionHandler||Code Block||Required. Upon execution passes back isSdkInitialized to provide information on the result of initialization. Also passes NSError reference to pass back error information in case of initialization issue.|
## Is Initialized
Returns BOOL to indicate if the SDK has been initialized.
## Reset SDK
Clears out SDK data. Clears processor data, client token block data, event initialization data, any data that was setup in Initialize SDK. Disconnects device. Allows consumer to start fresh with a reset instance of the SDK to help with changing users, clearing config.
|handler||Code Block||Required. Upon execution passed back isSdkReset to provide information on the result of reset. Also passes NSError reference to pass back error information in case of initialization issue.|
## Discover Devices
Discovers devices powered on and within range of the iOS device to be used with the SDK. **Currently only officially supported for Stripe M2 Reader device. If you have another brand of bluetooth reader turned on and in range, the discover devices may show the device. However, only Stripe M2 will currently work with Connect Device.**
Mobile device settings warning (Stripe M2)
For the Stripe M2 Reader, do not use your own mobile device settings when pairing with an M2 reader using the SDK. Pairing the reader through your mobile device settings may make the reader unavailable to connect through our SDK. Please rely on our ECPSdk to help guide the connection process.
|scanTime||NSUInteger||Required. Amount of time in seconds you would like to attempt to scan to discover devices. If 0 is passed in, the scanTime will default to a value of 5.|
|completionHandler||Code Block||Required. Indicates the discover process has finished. Upon execution passes back an array of ECPDevice to indicate devices that were successfully discovered. Also takes NSError to pass back any error information that occurs during the discover process.|
## Connect Device
**Currently only officially supported for Stripe M2 Reader device.** Connects to the card reader device and prepares the device to take payments, fire off events, report information. A reader can only connect to one instance of the SDK at a time. **Note - a reader may need to update on the connect process. The reader will not finish the connect process until required updates succeed. If a reader needs to update, ensure your reader is charged greater than 50 percent. Monitor ECPDeviceConfigStatusEvent and ECPDeviceConfigProgressEvent to track update status.**
|ECPDevice||ECPDevice||Device object which you would like to attempt to connect to. This should be a recently discovered device from the Discover Devices method. Note - this device must be charged and turned on in order to connect.|
|connectTimeout||NSUInteger||Required. Amount of time in approximate seconds that you would like to attempt the connect process. After this amount of time if the connect fails, the completion handler will be called with an error. If 0 is passed in, the connectTimeout will default to a value of 15 seconds.|
|completionHandler||Code Block||Required. Indicates the connect process has finished. Upon execution passes back isDeviceConnected to indicate if a device connection was successful. Passes back ECPDevice object that was used for the connect process. Also takes NSError to pass back any error information that occurs during the discover process.|
Example Implementation: See the example below. This example uses discover devices to discover available devices to use, and then as an example selects the first device in the devices array. The first device from the devices array is then passed into the connectDevice method. We then attempt to connect to the device.
## Disconnect Device
Disconnects the currently connected device.
|handler||Code Block||Required. Upon execution passed back didDisconnect to provide information on result of disconnect. Also passes NSError reference to pass back error information in case of disconnect issue.|
## Make Sale
Makes a sale for the amount specified. This requires that the SDK is initialized and that the Client Token Block above is set up correctly in order to retrieve a current client token for communication with PaySimple.
|parameters||ECPPaymentParameters||Required. The parameters used to create the payment.|
|completionHandler||Code Block||Required. Upon execution passed back ECPSaleResponse to provide information about the payment including whether it was successful or failed. Also passes NSError reference to pass back error information in case of payment failure.|
## Stop Current Flow
Stops a payment from completing. This can be done before the payment method is collected. Once the payment method is collected, the payment flow will run to completion.
|handler||Code Block||Required. Upon execution passes back didCancel to confirm that the flow was cancelled successfully. Also passes NSError reference to pass back error information in case of failure.|
## Get Device Info
Returns information about the connected device.
|handler||Code Block||Required. Upon execution passed back isDeviceConnected to provide information on if a device is currently connected to the SDK. Passed back an ECPDevice object with up to date properties for the specific device. Also passes NSError reference to pass back error information in case of Get Device Info issue.|
# Delegates / Events
The SDK provides an ECPSdkDelegate protocol to help expose delegate methods to report on SDK Events. Currently, the ECPSdkDelegate provides one optional method -(void)onDeviceEvent:(ECPSdkEvent \*)event; . In order to use this protocol within your application and listen to delegates, please mark the class you would like to use the protocol/delegate in as implementing the interface. For example, if you would like to use the protocol/delegate on the home page view controller of your application, your class declaration may look as follows:
In HomePageViewController.h file:
In HomePageViewController.m file, include the following delegate method:
The SDK also has an id<ECPSdkDelegate> type accessible through sharedECPSdk.delegate which needs to be wired up for use, to make everything work properly. You can wire up the delegate for use by attaching and wiring up to the delegate through a line of code like or similar to below in the class(es) which utilize the ECPSdkDelegate protocol:
## ECPSdkEvent Types
A generic type of event will be used as the base class for SDK events. This type is represented by a base class of ECPSdkEvent.
|error||NSError||Indicates any sort of error with ECPSdkEvent. If this property is not nil, there is an error on the ECPSdkEvent object, and error handling logic should be utilized, as the SDK will not have proper information on the SDK event objects.|
Different subclasses of ECPSdkEvent will be utilized to represent different events. These classes are represented in the charts below.
Event that fires when a device connection status change is reported.
|connection_status||NS_ENUM (ECPConnectionChangeStatus)||Indicates connection status of device. This enum can have the following potential enumvalues. These enum values are accessible to you as part of the ECPSdk: ECP_CONNECTION_STATUS_NOT_CONNECTED, ECP_CONNECTION_STATUS_CONNECTED, ECP_CONNECTION_STATUS_CONNECTING .|
Event that fires when a battery event is reported.
|battery_status||NS_ENUM (ECPBatteryEventStatus)||Indicates the type of battery status event that took place. These enum values are accessible to you as part of the ECPSdk: ECP_BATTERY_EVENT_LOW|
Event that fires when a card is inserted or removed.
|event_status||NS_ENUM (ECPCardEventStatus)||Indicates the type of device card event that took place. This enum can have the following potential values. These enum values are accessible to you as part of the ECPSdk: ECP_CARD_EVENT_INSERTED, ECP_CARD_EVENT_REMOVED|
Event that fires when a device attempts to prompt a user.
|promptMessage||NSString||Indicates that a message should be displayed to the user. (I.e. Insert Card, Remove Card, Try Again, Retry Card, etc.)|
|inputMessage||NSString||Indicated that the reader is waiting for input. Your app should prompt the customer to present a payment method using one of the given input options.|
Event that fires when a config event takes place from a device. **Note - on a config update event some readers may be unusable until required updates are completed.**
|event_status||NS_ENUM (ECPDeviceConfigEventStatus)||Indicates the type of config event that took place. This enum can have the following potential values. These enum values are accessible to you as part of the ECPSdk: ECP_CONFIG_EVENT_UPDATE_STARTED, ECP_CONFIG_EVENT_UPDATE_FINISHED|
Event that fires to report on config event progress.
|progress||float||Indicates the progress of a config event in the range of 0-100.|
## onDeviceEvent - Optional Delegate
Delegate fires when one of the subclasses of ECPSdkEvent is reported from the SDK and the SDK consumer has chosen to subscribe to the particular event. See **ECPSdkEventConstants and the subscribedEvents parameter in Initialize Sdk for how to specify which events you would like to subscribe to.**
|event||ECPSdkEvent||Generic type of event which will have a specific subclass type which one can use to handle events.|
Example Implementation: See the below code block for sample implementation of listening and reporting on device events. This particular example uses if else statements and class type to determine the type of ECPSdkEvent that came through. Consumers are free to determine their own best practice for their particular use case to determine the type of ECPSdkEvent, below is just one example. Consumers can then utilize the specific event type that is known to exist and access event specific information to utilize in their application.
Important: If you are utilizing information in delegates to update UI, please follow best practices and dispatch UI changes to the main thread.