iOS

  • Introduction

    The Yoco SDK for iOS allows for the integration of your applications into our payment platform.

    Your application will be able to accept credit/debit cards with a Yoco card reader (optionoally with the Yoco application installed on their devices).

  • Current Version 2.0.21


Getting started

Working with the SDK

The Yoco SDK is designed to work with applications supporting iOS 7.0 and above.

How the SDK works

The integrated solution works like any other 3rd party framework. During a transaction our Yoco UI will be overlayed over that of your app but will return control once the payment has been completed.

What do I need to start developing

To start building applications that make use of the Yoco SDK you will need the following:

  1. the Yoco SDK added to your application
  2. a Yoco developer account and associated secret for your application, which you can setup here

Setting up the SDK

The SDK is distributed as a framework for iOS. To get up and running with the SDK please follow the steps below:

  1. Download the latest SDK release (and extract the contents of the zip archive)
  2. Drag and drop all of the .framework and .bundle files into your project, selecting "Copy items if needed".

TutImage

  1. Add the following configuration to your Info.plist file to enable support for Bluetooth card readers:

    UISupportedExternalAccessoryProtocols: com.miura.shuttle
    UIBackgroundModes: external-accessory
    NSLocationWhenInUseUsageDescription: "Your location is used to ensure the security of your transactions"
    
  2. Add the following frameworks to your application:

    CoreBluetooth
    CoreLocation
    MediaPlayer.framework
    AVFoundation.framework
    Security.framework
    SystemConfiguration.framework
    ExternalAccessory.framework
    AudioToolbox.framework
    MediaPlayer.framework
    libstdc++.6.tbd
    libicucore.tbd
    CFNetwork.framework
    AssetsLibrary
    libxml2.tbd
    MobileCoreServices.framework
    CoreTelephony.framework
    QuartzCore.framework
    ImageIO.framework
    GLKit
    
  3. Add the following flag to "Other Linker Flags":

    -all_load
    
  4. Set "Enable Bitcode" to No

  5. Then, simply import the framework in your header file.

    #import <YocoSDK/YocoSDKClient.h>
    
  6. You are now ready to use the SDK! See "Getting started" to get set up for your first transaction.

If you have any questions, do not hesitate to contact us.


Getting started

Let's get started with some code examples to learn the basics of integrating with Yoco.

You can also download our Example App (please insert your API key and Secret in the AppDelegate.m file)

Step 1: Initialise your YocoClient

When using the SDK you have two options.

  1. Have users login to Yoco from within your application (this is usually the easiest approach if you will have lots of businesses using your integration)

  2. Have your application pass in a pre-configured API token for each business. You will need to co-ordinate with Yoco to create a token for each business that will use your integration.

When using either approach, you must also attach your YocoClientDelegate so that you can receive transaction results.

To allow your user to login to Yoco from within your app

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    //...your other code

    //Configure the YocoClient with your integrator secret (this identifies your software)
    [YocoClient initWithSecret:@"your-yoco-integration-secret"];

    //...more code

    return YES;
}

As soon as the business initiates their first Yoco transaction they will be shown a login dialog. If you would like to control when they are shown this dialog, you can force the login process by using the following:

[YocoClient login:self success:^{
    NSLog(@"Yoco logged in!");
} cancel:^{
    NSLog(@"User cancelled without logging in successfully");
}];

To use a pre-negotiated API token

[YocoClient initWithSecret:@"your-yoco-integration-secret" andApiToken:@"your-api-token"];

Step 2: Listen for events

Extend from the YocoClientDelegate to listen for events from the Yoco SDK.

/* Setup a YocoClientDelegate that will receive response events from the Yoco application */
#import <YocoClientDelegate.h>

@interface ExampleClientHandler : NSObject<YocoClientDelegate>
@end

Implement your handler

#import <YocoSDK/YocoSDKClient.h>

@implementation ExampleClientHandler
    /** handle successful transaction */
    -(void) handleTransactionSuccess:(YocoPaymentSuccessResponse*) response {
        NSLog(@"payment success")
    }

    /** handle failure of transaction */
    -(void) handleTransactionFailure:(YocoPaymentFailureResponse*) response {
        NSLog(response.message)
    }

    /** handle successful refund */
    -(void) handleRefundSuccess:(YocoRefundSuccessResponse *)response {
        NSLog(@"refund success")
    }

    /** handle failure of refund */
    -(void) handleRefundFailure:(YocoRefundFailureResponse *)response {
        NSLog(response.message)
    }
@end

After you have initialised your YocoClient you should attach your delegate

    //Setup your delegate and register it with the YocoClient
    ExampleClientHandler* yocoClientHandler = [[ExampleClientHandler alloc] init];
    [YocoClient setDelegate:yocoClientHandler];

Step 3: Start a transaction

You are then ready to start a transaction from inside your application.

-(void)examplePayment {
    //You must track which staff member performs each transaction for security purporses
    YocoStaff* staff = [[YocoStaff alloc] initWithStaffNumber:@"some-internal-staff-number"
                                          andName:@"Joe Bloggs"];

    //Simple payment with the YocoClient
    //2500 is R25.00 (amounts are always in cents)
    [YocoClient payCents:2500 withCurrency:@"ZAR" andStaff:staff];
}

API methods

Documentation for for the Yoco API and usage examples.

  • Process a payment

    Method

    [YocoClient payCents:amountInCents withCurrency:currency andStaff:staff]

    The pay method initiates a payment operation on the Yoco client application.

    Parameters

    Parameter Type Validation Notes
    amountInCents int Required
    currency NSString* Required Supported currency list
    staff YocoStaff* Required
  • Code Example
    //Create staff details for audit purposes
    YocoStaff* staff = [[YocoStaff alloc] initWithStaffNumber:@"some-internal-staff-number" andName:@"Joe Bloggs"];
    //Initiate a payment
    [YocoClient payCents:2500 withCurrency:@"ZAR" andStaff:staff];
    
  • Process a payment with settings

    Method

    [YocoClient payCents:amountInCents withCurrency:currency andSettings:settings andStaff:staff]

    Parameters

    Parameter Type Validation Notes
    amountInCents int Required
    currency NSString* Required Supported currency list
    settings YocoPaymentSettings* Required
    staff YocoStaff* Required
  • Code Example
    //Settings object with payment settings you want
    YocoPaymentSettings* settings = [[YocoPaymentSettings alloc]init]
    [settings setReceiptNumber: @"123-456-7889"];
    [settings setReceiptEmail: @"[email protected]"];
    
    //Create staff details for audit purposes
    YocoStaff* staff = [[YocoStaff alloc] initWithStaffNumber:@"some-internal-staff-number"
                                          andName:@"Joe Bloggs"];
    
    //Initiate a payment
    [YocoClient payCents:2500 withCurrency:@"ZAR" andSettings: settings andStaff: staff];
    

Class definitions

  • Payment Settings

    Object

    YocoPaymentSettings

    Settings related to the payment that is being made.

    Members

    Variable Type Validation Notes
    receiptNumber NSString* Optional
    receiptEmail NSString* Optional
    paymentIdentifier NSString* Optional A unique identifier for this payment - used to ensure that a payment is never processed twice.
    tipAmountInCents NSInteger Optional defaults to 0 - NB: this amount will be added to the total cents amount
    offerTipEntry BOOL Optional defaults to NO
    note NSString* Optional
    items NSArray* Optional An array of YocoItem
  •  
  • Items

    Object

    YocoItem

    Items that will be stored for the transaction.

    Members

    Variable Type Validation Notes
    description NSString* Optional
    name NSString* Required
    price NSInteger Required
    vatEnabled BOOL Optional
    quantity NSInteger Optional
  •  
  • Staff

    Object

    YocoStaff

    Details of the staff member performing the transaction.

    Members

    Variable Type Validation Notes
    number NSString* Required Staff number internal to merchant
    name NSString* Optional
  •  
  • Payment Success Response

    Object

    YocoPaymentSuccessResponse

    Response received by the YocoClientDelegate when a payment is successfully processed.

    Members

    Variable Type Notes
    code YocoResponseCode* An enum with a value of YCResponseSuccess
    message NSString* Detailed message returned from the Yoco server
    paymentIdentifier NSString* Yoco payment ID to prevent duplicate transactions
    receiptDetails YocoReceiptDetails* Receipt details for transaction
  •  
  • Payment Failure Response

    Object

    YocoPaymentFailureResponse

    Response received by the YocoClientDelegate when a payment fails.

    Members

    Variable Type Notes
    code YocoResponseCode* An enum with a response code.
    message NSString* Detailed message about the cause of the error from the Yoco server
    paymentIdentifier NSString* Yoco payment ID to prevent duplicate transactions
    receiptDetails YocoReceiptDetails* Receipt details for transaction
  •  
  • Refund Success Response

    Object

    YocoRefundSuccessResponse

    Response received by the YocoClientDelegate when a refund is successfully processed.

    Members

    Variable Type Notes
    code YocoResponseCode* An enum with a value of YCResponseSuccess
    message NSString* Detailed message returned from the Yoco server
    paymentIdentifier NSString* Yoco payment ID to prevent duplicate transactions
    receiptDetails YocoReceiptDetails* Receipt details for transaction
  •  
  • Refund Failure Response

    Object

    YocoRefundFailureResponse

    Response received by the YocoClientDelegate when a refund fails.

    Members

    Variable Type Notes
    code YocoResponseCode* An enum with a response code.
    message NSString* Detailed message about the cause of the error from the Yoco server
    paymentIdentifier NSString* Yoco payment ID to prevent duplicate transactions
    receiptDetails YocoReceiptDetails* Receipt details for transaction
  •  
  • Response Code

    Enum

    YocoResponseCode

    Response code for all transactions - failed and succeeded. These are bit flags and are combined depending on the range of errors present in the request. The bit values are shown in brackets below.

    Values

    Value Notes
    YCResponseSuccess Transaction succeeded (1)
    YCResponseFailed Transaction failed (check receipt info for details) (2)
    YCResponseMissingParameter Payment request was missing a required parameter (4)
    YCResponseParserError Amount to be paid could not be parsed (8)
    YCResponseInvalidToken The supplied API token is invalid (16)
    YCResponseInvalidSecret The supplied app secret is invalid (32)
    YCResponseInvalidCurrency The supplied currency is not yet supported (only ZAR) (64)
    YCResponseError Generic error (please see the message field for details) (128)
  •  
  • Receipt Details

    Object

    YocoReceiptDetails

    Details for a valid receipt returned from a transaction. All these fields should be included in the receipt. An example is provided below:

    TutImage

    Members

    Variable Type Notes
    type YocoTransactionType An enum of the transaction type (3)
    state YocoTransactionState An enum of the transaction state
    paymentScheme NSString* VISA or MasterCard (6)
    maskedAccountNumber NSString* e.g. 412302**4081 (7)
    authorizationCode NSString* (8)
    transactionIdentifier NSString* (9)
    merchantIdentifier NSString* (12)
    terminalIdentifier NSString* (13)
    entryMode YocoPaymentEntryMode An enum of the payment entry mode (14)
    applicationIdentifier NSString* AID (15)
    verificationResult NSString* TVR (15)
    transactionStatusInformation NSString* TSI (15)
    pwIdentifier NSString* PWID (16)
    printForMerchantAndCustomer BOOL Print a copy for the customer as well as the merchant
    requiresSignature BOOL The printed copy requires a signature from the customer
    signatureText NSString* Text to be displayed below the signature area on the merchant receipt
    statusText NSString* (10)
  •  
  • Transaction Type

    Enum

    YocoTransactionType

    Enum for various transaction types.

    Values

    Value Notes
    YCTransactionTypeCash
    YCTransactionTypeCard
  •  
  • Transaction State

    Enum

    YocoTransactionState

    Enum for various transaction states.

    Values

    Value Notes
    YCTransactionStateApproved Transaction was authorised
    YCTransactionStateDeclined Transaction was declined by bank
    YCTransactionStateAborted Transaction was canceled by customer
    YCTransactionStateInvalid Unexpected error on transaction
    YCTransactionStateReversed Transaction was reversed
    YCTransactionStateRefunded Transaction was refunded
    YCTransactionStateChargeBack Transaction was charged back
  •  
  • Payment Entry Mode

    Enum

    YocoPaymentEntryMode

    Enum for various payment entry modes.

    Values

    Value Notes
    YCEntryModeChipAndPin EMV chip and pin
    YCEntryModeMagstripe For Magstripe and Magstripe as fallback
    YCEntryModeContactless NFC (PayPass or PayWave)
    YCentryModeCash Cash payment
  •  
  • Client Delegate

    Protocol

    YocoClientDelegate

    The client delegate should be implemented and set as the delegate in the YocoClient.

    Methods

    Method Signiture
    handleTransactionSuccess -(void) handleTransactionSuccess:(YocoPaymentSuccessResponse*) response;
    handleTransactionFailure -(void) handleTransactionFailure:(YocoPaymentFailureResponse*) response;
    handleRefundSuccess -(void) handleRefundSuccess:(YocoRefundSuccessResponse*) response;
    handleRefundFailure -(void) handleRefundFailure:(YocoRefundFailureResponse*) response;
  • Code Example
    /*
    This is the implementation for a class
    implementing the YocoClientDelegate protocol
    */
    @implementation ExampleClientHandler
        /** handle successful transaction */
        -(void) handleTransactionSuccess:(
                YocoPaymentSuccessResponse*) response{
            NSLog(@"payment success")
        }
    
        /** handle failure of transaction */
        -(void) handleTransactionFailure:(
                YocoPaymentFailureResponse*) response{
            NSLog(response.errorMessage)
        }
    @end
    
  • Yoco Api Client

    Object

    YocoClient

    The YocoClient is responsible for initiating transactions and other Yoco related functions.

    Methods

    Method Signiture
    init -(id) initWithSecret:(NSString*)secret andApiToken:(NSString*);
    -(id) initWithSecret:(NSString*)secret;
    payCents -(void) payCents(NSInteger):amountInCents withCurrency(NSString*):currency andStaff:(YocoStaff*)staff;
    -(void) payCents(NSInteger):amountInCents withCurrency(NSString*):currency andSettings:(YocoPaymentSettings*)settings andStaff:(YocoStaff*)staff;
    login -(void) login:(UIViewController*)viewController success:(void (^)())success cancel:(void (^)())cancel
    logout -(void) logout;
    setAPIToken -(void) setAPIToken:(NSString*) apiToken;
    setDelegate -(void) setDelegate:(YocoClientDelegate*) delegate;
    refund -(void) refund:(NSString*)pwIdentifier withStaff:(YocoStaff*)staff;
  • Example Code
    //Configure the YocoClient with your API token and URL schema
    [YocoClient initWithSecret:@"some-secret-token"];
    
    //Setup your delegate and register it with the YocoClient
    ExampleClientHandler* yocoClientHandler = [[ExampleClientHandler alloc] init];
    [YocoClient setDelegate:yocoClientHandler];
    
    //Create staff details for audit purposes
    YocoStaff* staff = [[YocoStaff alloc] initWithStaffNumber:@"some-internal-staff-number"
                                          andName:@"Joe Bloggs"];
    
    //Make a payment
    [YocoClient payCents:2500 withCurrency:@"ZAR" andStaff:staff];
    
  • Supported Currency Values

    Values

    The YocoClient can accept the following currencies in its payCents method.

    Values

    Value Notes
    @"ZAR" South African Rand
  •