goSell iOS SDK

iOS SDK to use goSell API.

A library that fully covers payment/authorization/card saving process inside your iOS application.

Table of Contents

1. Requirements
2. Installation
   1. Installation with CocoaPods
3. Setup
   1. goSellSDK Class Properties
   2. goSellSDK Class Methods
   3. Setup Steps
4. Usage
   1. SDK modes
   2. Pay Button
      1. Pay Button Placement
      2. Properties
      3. Methods
   3. Session
      1. Properties
      2. Methods
   4. API Session
      1. Properties
      2. Methods
   5. Session Data Source
      1. Structure
      2. Samples
   6. Session Delegate
      1. Payment Success Callback
      2. Payment Failure Callback
      3. Authorization Success Callback
      4. Authorization Failure Callback
      5. Card Saving Success Callback
      6. Card Saving Failure Callback
      7. Card Tokenization Success Callback
      8. Card Tokenization Failure Callback
      9. Session Is Starting Callback
      10. Session Has Started Callback
      11. Session Has Failed to Start Callback
      12. Session Cancel Callback
   7. Session Appearance
5. Sample

Requirements

To use the SDK the following requirements must be met:

1. Xcode 10.0 or newer
2. Swift 4.2 or newer (preinstalled with Xcode)
   
3. Base SDK for the target app: iOS 8.0 or later

Installation

Installation with CocoaPods

CocoaPods is a dependency manager, which automates and simplifies the process of using 3rd-party libraries in your projects.
You can install it with the following command:

$ gem install cocoapods

Podfile

To integrate goSellSDK into your Xcode project using CocoaPods, specify it in your Podfile:

platform :ios, '8.0'
use_frameworks!

source 'https://github.com/CocoaPods/Specs.git'

target 'MyApp' do

    pod 'goSellSDK'

end

Then, run the following command:

$ pod update

We also recommend you to include ErrorReporting submodule in order to allow your customers to report unexpected behaviour of the SDK directly to Tap.

To include error reporting, please add the following line to your Podfile:

target 'MyApp' do

    # Other pods
    ...

    # Error reporting submodule.
    pod 'goSellSDK/ErrorReporting' 

end

Setup

First of all, goSellSDK should be set up. In this section only secret key is required.

goSellSDK Class Properties

Below is the list of properties in goSellSDK class you can manipulate. Make sure you do the setup before any usage of the SDK.

Secret Key

To set it up, add the following line of code somewhere in your project and make sure it will be called before any usage of goSellSDK, otherwise an exception will be thrown. Required.

Swift:

let secretKey = SecretKey(sanbox: "YOUR_SANDBOX_SECRET_KEY", production: "YOUR_PRODUCTION_SECRET_KEY") // (format of the key: "sk_XXXXXXXXXXXXXXXXXXXXXXXX")
goSellSDK.secretKey = secretKey // Secret key (format: "sk_XXXXXXXXXXXXXXXXXXXXXXXX")

Objective-C:

SecretKey *secretKey = [[SecretKey alloc] initWithSandbox:@"YOUR_SANDBOX_SECRET_KEY" production:@"YOUR_PRODUCTION_SECRET_KEY"]; // (format of the key: "sk_XXXXXXXXXXXXXXXXXXXXXXXX")
[goSellSDK setSecretKey:secretKey];

Don’t forget to import the framework at the beginning of the file:

Swift:

import goSellSDK

Objective-C:

@import goSellSDK;

or

#import <goSellSDK/goSellSDK-Swift.h>

Mode

SDK mode is a mode SDK is operating in, either sandbox or production.

Use this property to test your integration with the sandbox transactions.

WARNING: Default value of this property is production which means your transaction are real transactions. Switch to sandbox while in development.

Language

Localization language of the UI part of the SDK. This is locale identifier.

Make sure it consists only from 2 lowercased letters and is presented in the list of availableLanguages property of goSellSDK class.

Notice: Starting from iOS 9 SDK user interface layout direction is based on the language you select, which means that if you would like to have it in Arabic language, the UI will be switched to RTL (right-to-left).

Available Languages

This property returns the list of locale identifiers the SDK is currently localized into.

Currently we support the following languages:

SDK Version

This property returns current SDK version.

goSellSDK Class Methods

Reset

Resets all settings and makes the SDK to reinitialize on next usage.
Might be useful when you are switching accounts.
Also when you are logging the user out, although that’s not required.

Setup Steps

With PayButton

For those, who would like to use PayButton.

1. Place PayButton.
2. Assign its datasource and delegate.
3. Implement datasource and delegate.

Without PayButton

For those who would like to keep their design and start the SDK process manually.

1. Create Session object.
2. Assign its datasource and delegate.
3. Implement datasource and delegate.

Usage

After goSellSDK is set up, you can actually use the SDK.
We have tried to make the SDK integration as simple as possible, requiring the minimum from you.

SDK Modes

goSellSDK works in 4 modes:

1. Purchase: Default mode. Normal customer charge.
2. Authorize: Only authorization is happening. You should specify an action after successful authorization: either capture the amount or void the charge after specific period of time.
3. Card Saving: Use this mode to save the card of the customer with Tap and use it later.
4. Card Tokenization: Use this mode if you are willing to perform the charging/authorization manually. The purpose of this mode is only to collect and tokenize card information details of your customer if you don’t have PCI compliance certificate but willing to process the payment manually using our services.

The mode is set through SessionDataSource interface.

Pay Button

Here at Tap, we have designed our custom Pay button and all you need to do is just to put it somewhere on the screen and provide at least required payment details through its dataSource property.

Pay Button Placement

Pay Button is restricted to the height of exactly 44 points. For better experience, make sure that it has enough width to display the content.

XIB/Storyboard

You can add Pay button on your view in XIB/Storyboard file. To do that, do the following:

1. Drag & drop an instance of UIView at the desired location.
2. Select added view and open Identity Inspector
3. Enter the following values:
   1. Class: PayButton
   2. Module: goSellSDK
4. For your convenience, you may also connect dataSource and delegate outlets.

Code

You can also add Pay button with the code:

Swift:

import goSellSDK
...
func addPayButton() {

    let buttonFrame = CGRect(x: 8.0, y: UIScreen.main.bounds.height - 52.0, width: UIScreen.main.bounds.width - 16.0, height: 44.0)
    let button = PayButton(frame: buttonFrame)
    self.view.addSubview(button) // or where you want it

    button.dataSource = self // or whatever
    button.delegate = self // or whatever
}

Objective-C:

@import goSellSDK;
...
- (void)addPayButton {

    CGRect buttonFrame = CGRectMake(8.0, UIScreen.mainScreen.bounds.size.height - 52.0, UIScreen.mainScreen.bounds.size.width - 16.0, 44.0);
    PayButton *button = [[PayButton alloc] initWithFrame:buttonFrame];
    [self.view addSubview:button]; // or where you want it

    button.dataSource = self; // or whatever
    button.delegate = self; // or whatever
}

Properties

Below is the list of Pay button properties

Methods

Session

You want to use Session object if you are not using PayButton.

Properties

Methods

API Session

APISession is a class you want to use when you need to call plain APIs without the UI. Currently not all APIs are available.

Properties

Methods

Please refer to APISession class documentation for more details.

Session Data Source

SessionDataSource is an interface which you should implement somewhere in your code to pass payment information in order to be able to access payment flow within the SDK.

Strucure

The following table describes its structure and specifies which fields are required for each of the modes.

Samples

Mode

Objective-C

- (enum TransactionMode)mode {

    return Purchase;
}

Swift

var mode: TransactionMode {

    return .purchase
}

Customer

Objective-C

- (Customer *)customer {

    if ( customerIDIsKnown ) {

        return [self identifiedCustomer];
    }
    else {

        return [self newCustomer];
    }
}

/// Creating a customer with known identifier received from Tap before.
- (Customer *)identifiedCustomer {

    return [[Customer alloc] initWithIdentifier:@"cus_tomer_id"];
}

/// Creating a customer with raw information.
- (Customer *)newCustomer {

    EmailAddress *email = [EmailAddress withEmailAddressString:@"customer@mail.com"];
    PhoneNumber *phoneNumber = [[PhoneNumber alloc] initWithISDNumber:@"965" phoneNumber:@"96512345"];

    Customer *newCustomer = [[Customer alloc] initWithEmailAddress:email
                                                       phoneNumber:phoneNumber
                                                         firstName:@"Steve"
                                                        middleName:nil
                                                          lastName:@"Jobs"];

    return newCustomer;
}

Swift

var customer: Customer? {

    if customerIDIsKnown {

        return self.identifiedCustomer
    }
    else {

        return self.newCustomer
    }
}

/// Creating a customer with known identifier received from Tap before.
var identifiedCustomer: Customer? {

    return try? Customer(identifier: "cus_to_mer")
}

/// Creating a customer with raw information. 
var newCustomer: Customer? {

    let emailAddress = try! EmailAddress(emailAddressString: "customer@mail.com")
    let phoneNumber = try! PhoneNumber(isdNumber: "965", phoneNumber: "96512345")

    return try? Customer(emailAddress:  emailAddress,
                         phoneNumber:   phoneNumber,
                         firstName:     "Steve",
                         middleName:    nil,
                         lastName:      "Jobs")
}

Currency

Tap supports processing payments in 10+ currencies, allowing you to charge customers in their native currency while receiving funds in yours. This is especially helpful if you have a global presence, as charging in a customer’s native currency can increase sales.

SupportedCurrencies

Objective-C

- (Currency *)currency {

    return [Currency withISOCode:@"KWD"];
}

Swift

var currency: Currency? {

    return .with(isoCode: "KWD")
}

Amount

Objective-C

- (NSDecimal)amount {

    return [NSDecimalNumber one].decimalValue;
}

Swift

var amount: Decimal {

    return 1.0
}

Items

Objective-C

- (NSArray<PaymentItem *> *)items {

    Quantity *oneUnit = [[Quantity alloc] initWithValue:[NSDecimalNumber one].decimalValue
                                      unitOfMeasurement:[Measurement units]];
    NSDecimal ten = [[NSDecimalNumber one] decimalNumberByMultiplyingByPowerOf10:1].decimalValue;

    PaymentItem *firstItem = [[PaymentItem alloc] initWithTitle:@"Test item #1"
                                                       quantity:oneUnit
                                                  amountPerUnit:ten];


    NSDecimal oneHundred = [[NSDecimalNumber one] decimalNumberByMultiplyingByPowerOf10:2].decimalValue;
    Quantity *oneHundredSquareMeters = [[Quantity alloc] initWithValue:oneHundred unitOfMeasurement:[Measurement area:SquareMeters]];

    NSDecimal seventeen = [NSDecimalNumber numberWithDouble:17.0].decimalValue;

    AmountModificator *tenPercents = [[AmountModificator alloc] initWithPercents:ten];

    NSDecimal oneThousand = [[NSDecimalNumber one] decimalNumberByMultiplyingByPowerOf10:3].decimalValue;

    AmountModificator *thousandMoney = [[AmountModificator alloc] initWithFixedAmount:oneThousand];
    Tax *thousandKD = [[Tax alloc] initWithTitle:@"KD 1,000.000" descriptionText:@"This is an example of a tax." amount:thousandMoney];

    PaymentItem *secondItem = [[PaymentItem alloc] initWithTitle:@"Test item #2"
                                                 descriptionText:@"Test item #2 awesome description"
                                                        quantity:oneHundredSquareMeters
                                                   amountPerUnit:seventeen
                                                        discount:tenPercents
                                                           taxes:@[thousandKD]];

    return @[firstItem, secondItem];
}

Swift

var items: [PaymentItem]? {

    let oneUnit = Quantity(value: 1, unitOfMeasurement: .units)
    let firstItem = PaymentItem(title:          "Test item #1",
                                quantity:       oneUnit,
                                amountPerUnit:  10)

    let oneHundredSquareMeters = Quantity(value:                100,
                                          unitOfMeasurement:    .area(.squareMeters))
    let tenPercents = AmountModificator(percents: 10)
    let thousandMoney = AmountModificator(fixedAmount: 1000)
    let thousandKD = Tax(title:             "KD 1,000.000",
                         descriptionText:   "This is an example of a tax.",
                         amount: thousandMoney)

    let secondItem = PaymentItem(title:             "Test item #2",
                                 descriptionText:   "Test item #2 awesome description.",
                                 quantity:          oneHundredSquareMeters,
                                 amountPerUnit:     17,
                                 discount:          tenPercents,
                                 taxes:             [thousandKD])

    return [firstItem, secondItem]
}

Taxes

Objective-C

- (NSArray<Tax *> *)taxes {

    NSDecimal fifteen = [NSDecimalNumber numberWithDouble:15.0].decimalValue;
    AmountModificator *fifteenPercents = [[AmountModificator alloc] initWithPercents:fifteen];

    Tax *fifteenPercentsTax = [[Tax alloc] initWithTitle:@"15 percents"
                                         descriptionText:@"Just another fifteen percents."
                                                  amount:fifteenPercents];

    return @[fifteenPercentsTax];
}

Swift

var taxes: [Tax]? {

    let fifteenPercents = AmountModificator(percents: 15)

    let fifteenPercentsTax = Tax(title:             "15 percents",
                                 descriptionText:   "Just another fifteen percents",
                                 amount:            fifteenPercents)

    return [fifteenPercentsTax]
}

Shipping

Objective-C

- (NSArray<Shipping *> *)shipping {

    NSDecimal fiveHundred = [NSDecimalNumber numberWithDouble:500.0].decimalValue;
    Shipping *deliveryToHome = [[Shipping alloc] initWithName:@"Delivery"
                                              descriptionText:@"Delivery to Home"
                                                       amount:fiveHundred];

    return @[deliveryToHome];
}

Swift

var shipping: [Shipping]? {

    let deliveryToHome = Shipping(name:             "Delivery",
                                  descriptionText:  "Delivery to Home",
                                  amount:           500)
    return [deliveryToHome]
}

Post URL

Objective-C

- (NSURL *)postURL {

    return [NSURL URLWithString:@"https://tap.company/post"];
}

Swift

var postURL: URL? {

    return URL(string: "https://tap.company/post")
}

Payment Description

Objective-C

- (NSString *)paymentDescription {

    return @"Awesome payment description will be here.";
}

Swift

var paymentDescription: String? {

    return "Awesome payment description will be here.";
}

Payment Metadata

Objective-C

- (NSDictionary<NSString *,NSString *> *)paymentMetadata {

    return @{@"note": @"some note",
             @"internal_linking_id": @"id3424141414"};
}

Swift

var paymentMetadata: [String : String]? {

    return [

        "note": "some note",
        "internal_linking_id": "id3424141414"
    ]
}

Payment Reference

Objective-C

- (Reference *)paymentReference {

    return [[Reference alloc] initWithTransactionNumber:@"tr_2352358020f"
                                            orderNumber:@"ord_2352094823"];
}

Swift

var paymentReference: Reference? {

    return Reference(transactionNumber: "tr_2352358020f",
                     orderNumber:       "ord_2352094823")
}

Payment Statement Descriptor

Objective-C

- (NSString *)paymentStatementDescriptor {

    return @"Payment statement descriptor will be here";
}

Swift

var paymentStatementDescriptor: String? {

    return "Payment statement descriptor will be here"
}

Require 3D Secure

Objective-C

- (BOOL)require3DSecure {

    return YES;
}

Swift

var require3DSecure: Bool {

    return true
}

Receipt Settings

Objective-C

- (Receipt *)receiptSettings {

    return [[Receipt alloc] initWithEmail:YES sms:YES];
}

Swift

var receiptSettings: Receipt? {

    return Receipt(email: true, sms: true)
}

Authorize Action

Objective-C

- (AuthorizeAction *)authorizeAction {

    AuthorizeAction *captureAfterTwoHours = [AuthorizeAction captureAfterTimeInHours:2];
    return captureAfterTwoHours;
}

Swift

var authorizeAction: AuthorizeAction {

    return .capture(after: 2)
}

Allows to Save Same Card More Than Once

Objective-C

- (BOOL)allowsToSaveSameCardMoreThanOnce {

    return NO;
}

Swift

var allowsToSaveSameCardMoreThanOnce: Bool {

    return false
}

Session Delegate

SessionDelegate is an interface which you may want to implement to receive payment/authorization/card saving status updates and update your user interface accordingly when payment window closes.

Below are listed down all available callbacks:

Payment Success Callback

Notifies the receiver that payment has succeed. Can be called only in purchase mode.

Declaration

Objective-C:

- (void)paymentSucceed:(Charge * _Nonnull)charge onSession:(id <SessionProtocol> _Nonnull)session;

Swift:

func paymentSucceed(_ charge: Charge, on session: SessionProtocol)

Arguments

charge: Successful charge object.

session: Session object. It can be either a PayButton or an instance of Session if you are not using PayButton.

Payment Failure Callback

Notifies the receiver that payment has failed. Can be called only in purchase mode.

Declaration

Objective-C:

- (void)paymentFailedWithCharge:(Charge * _Nullable)charge error:(TapSDKError * _Nullable)error onSession:(id <SessionProtocol> _Nonnull)session;

Swift:

func paymentFailed(with charge: Charge?, error: TapSDKError?, on session: SessionProtocol)

Arguments

charge: Charge object that has failed (if reached the stage of charging).

error: An error that has occured (if any).

session: Session object. It can be either a PayButton or an instance of Session if you are not using PayButton.

You may assume that at least one, charge or error is not nil.

Authorization Success Callback

Notifies the receiver that authorization has succeed. Can be called only in authorization mode.

Declaration

Objective-C:

- (void)authorizationSucceed:(Authorize * _Nonnull)authorize onSession:(id <SessionProtocol> _Nonnull)session;

Swift:

func authorizationSucceed(_ authorize: Authorize, on session: SessionProtocol)

Arguments

authorize: Successful authorize object.

session: Session object. It can be either a PayButton or an instance of Session if you are not using PayButton.

Authorization Failure Callback

Notifies the receiver that authorization has failed. Can be called only in authorization mode.

Declaration

Objective-C:

- (void)authorizationFailedWithAuthorize:(Authorize * _Nullable)authorize error:(TapSDKError * _Nullable)error onSession:(id <SessionProtocol> _Nonnull)session;

Swift:

func authorizationFailed(with authorize: Authorize?, error: TapSDKError?, on session: SessionProtocol)

Arguments

authorize: Authorize object that has failed (if reached the stage of authorization).

error: An error that has occured (if any).

session: Session object. It can be either a PayButton or an instance of Session if you are not using PayButton.

You may assume that at least one, authorize or error is not nil.

Card Saving Success Callback

Notifies the receiver that the customer has successfully saved the card. Can be called only in card saving mode.

Declaration

Objective-C:

- (void)cardSaved:(CardVerification * _Nonnull)cardVerification onSession:(id <SessionProtocol> _Nonnull)session;

Swift:

func cardSaved(_ cardVerification: CardVerification, on session: SessionProtocol)

Arguments

cardVerification: Card verification object with the details.

session: Session object. It can be either a PayButton or an instance of Session if you are not using PayButton.

Card Saving Failure Callback

Notifies the receiver that the customer failed to save the card. Can be called only in card saving mode.

Declaration

Objective-C:

- (void)cardSavingFailedWithCardVerification:(CardVerification * _Nullable)cardVerification error:(TapSDKError * _Nullable)error onSession:(id <SessionProtocol> _Nonnull)session;

Swift:

func cardSavingFailed(with cardVerification: CardVerification?, error: TapSDKError?, on session: SessionProtocol)

Arguments

cardVerification: Card verification object with the details (if reached the stage of card saving).

error: Error that has occured. If nil, please refer to the cardVerification object for error details.

session: Session object. It can be either a PayButton or an instance of Session if you are not using PayButton.

Card Tokenization Success Callback

Notifies the receiver that card token has successfully created. Can be called only in card tokenization mode.

Declaration

Objective-C:

- (void)cardTokenized:(Token * _Nonnull)token onSession:(id <SessionProtocol> _Nonnull)session customerRequestedToSaveTheCard:(BOOL)saveCard;

Swift:

func cardTokenized(_ token: Token, on session: SessionProtocol, customerRequestedToSaveTheCard saveCard: Bool)

Arguments

token: Token of the card provided by your customer. session: Session object. It can be either a PayButton or an instance of Session if you are not using PayButton. saveCard: Boolean flag which determines whether the customer wants to save the card. Actual card saving process is not happening.

Card Tokenization Failure Callback

Notifies the receiver that card token has failed to be created. Can be called only in card tokenization mode.

Declaration

Objective-C:

- (void)cardTokenizationFailedWithError:(TapSDKError * _Nonnull)error onSession:(id <SessionProtocol> _Nonnull)session;

Swift:

func cardTokenizationFailed(with error: TapSDKError, on session: SessionProtocol)

Arguments

error: Error that has occured. session: Session object. It can be either a PayButton or an instance of Session if you are not using PayButton.

Session Is Starting Callback

Notifies the receiver that session is about to start, but hasn’t yet shown the SDK UI. You might want to use this method if you are not using PayButton in your application and want to show a loader before SDK UI appears on the screen. Will be called in all modes.

Declaration

Objective-C:

- (void)sessionIsStarting:(id <SessionProtocol> _Nonnull)session;

Swift:

func sessionIsStarting(_ session: SessionProtocol)

Arguments

session: Session object. It can be either a PayButton or an instance of Session if you are not using PayButton.

Session Has Started Callback

Notifies the receiver that session has successfully started and shown the SDK UI on the screen. You might want to use this method if you are not using PayButton in your application and want to hide a loader after SDK UI has appeared on the screen. Will be called in all modes.

Declaration

Objective-C:

- (void)sessionHasStarted:(id <SessionProtocol> _Nonnull)session;

Swift:

func sessionHasStarted(_ session: SessionProtocol)

Arguments

session: Session object. It can be either a PayButton or an instance of Session if you are not using PayButton.

Session Has Failed to Start Callback

Notifies the receiver that session has failed to start and will not show the SDK UI on the screen. You might want to use this method if you are not using PayButton in your application and want to hide a loader because the session has failed. For the actual failure cause please implement other methods from this protocol and listen to the callbacks. Will be called in all modes.

Declaration

Objective-C:

- (void)sessionHasFailedToStart:(id <SessionProtocol> _Nonnull)session;

Swift:

func sessionHasFailedToStart(_ session: SessionProtocol)

Arguments

session: Session object. It can be either a PayButton or an instance of Session if you are not using PayButton.

Session Cancel Callback

Notifies the receiver that payment/authorization was cancelled by user. Will be called in all modes.

Declaration

Objective-C:

- (void)sessionCancelled:(id <SessionProtocol> _Nonnull)session;

Swift:

func sessionCancelled(_ session: SessionProtocol)

Arguments

session: Session object. It can be either a PayButton or an instance of Session if you are not using PayButton.

Session Appearance

You might want to implement SessionAppearance protocol if you need some UI customization to match your user interface and provide great user experience.

Please refer to SessionAppearance class documentation to see what kind of customization is currently available.

Sample

Sample application integration is available in Example folder.

Documentation

Documentation is available at github-pages.
Also documented sources are attached to the library.