# Models

## ECPDevice

id_numberNSStringId (serial) number of device.
manufacturerNSStringManufacturer/brand of device.
modelNSStringModel of device.
battery_percentageNSStringBattery percentage of device between 0-100%.

## ECPPaymentParameters

amountNSNumberRequired. Amount to charge. Must be a positive number.
paymentDescriptionNSStringOptional. 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.
paymentDescriptionSuffixNSStringOptional. 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.
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.
duplicate_checkNSString**WORLDPAY/EXPRESS ONLY** Optional. Default:"enabled" Valid values: "enabled", "disabled". Indicates the duplicate check mode.
captureNSString**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_approvalsBOOL**WORLDPAY/EXPRESS ONLY** Optional. Default: FALSE. If true, allows partial approvals. Most useful for gift cards with limited funds.

## ECPSdkEventConstants

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.

## ECPSaleResponse

transaction_idNSStringUnique Id of transaction.
acqurier_messageNSStringAcquirer message returned. Do not base application logic on this message as it may change without notice.
authorization_codeNSStringAcquirer Authorization code.
approved_amountNSDecimalNumberAmount approved.
batch_idNSNumberSettlement batch id (card only). **Value will be nil for Stripe processed payments.**
cardECPCardDataCard response
outcomeECPSaleOutcomeSale outcome
emvECPEmvDataEMV response data if present
entry_modeNSStringEntry mode of transaction

## ECPSaleOutcome

resultNSStringResult of transaction request. Valid values "success", "failed", "declined"
codeNSString4-digit PaySimple result code.
outcome_descriptionNSDecimalNumberDescription of decline, failure or success.

## ECPCardData

card_brandNSStringCard brand type.
last4NSStringLast 4 digits of card number.
card_holder_nameNSStringName of cardholder
expiration_monthNSNumberMonth of card expiration
expiration_yearNSNumberYear of card expiration in 4 digit format.

## ECPEmvData

application_identifierNSStringApplication Identifier.
application_preferred_nameNSStringApplication Preferred Name.
application_labelNSStringApplication Label. **Value will be nil for Stripe payments.**
application_cryptogramNSStringCryptogram value.
authorization_response_codeNSStringAuthorization Response Code.
authorization_response_messageNSStringAuthorization Response Message.
is_pin_verifiedBOOLWhether 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.

Example Implementation:

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

environmentNSStringRequired. Environment to use. Possible values: "SBX" for sandbox or "PROD" for production
subscribedEventsNSSetSet 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];
clientTokenBlockCode BlockRequired. 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.
completionHandlerCode BlockRequired. 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.

Example Implementation:

## Is Initialized

Returns BOOL to indicate if the SDK has been initialized.

Example Implementation:

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

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

Example Implementation:

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

scanTimeNSUIntegerRequired. 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.
completionHandlerCode BlockRequired. 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.

Example Implementation:

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

ECPDeviceECPDeviceDevice 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.
connectTimeoutNSUIntegerRequired. 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.
completionHandlerCode BlockRequired. 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.

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

Example Implementation:

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

parametersECPPaymentParametersRequired. The parameters used to create the payment.
completionHandlerCode BlockRequired. 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.

Example implementation:

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

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

Example implementation:

## Get Device Info

Returns information about the connected device.

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

Example Implementation:

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


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

promptMessageNSStringIndicates that a message should be displayed to the user. (I.e. Insert Card, Remove Card, Try Again, Retry Card, etc.)
inputMessageNSStringIndicated 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_statusNS_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.

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

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