Omise iOS SDK

Omise is a payment service provider operating in Thailand, Japan, and Singapore. Omise provides a set of APIs that help merchants of any size accept payments online.

The Omise iOS SDK provides bindings for tokenizing credit cards and accepting non-credit-card payments using the Omise API allowing developers to safely and easily accept payments within apps.

If you run into any issues regarding this SDK and the functionality it provides, consult the frequently asked questions in our comprehensive support documents. If you can't find an answer there, post a question in our forum or feel free to email our support team.

Requirements

• Omise API public key. Register for an Omise account to obtain your API keys.
• iOS 8 or higher deployment target.
• Xcode 10.0 or higher (Xcode 11 is recommended)
• Swift 5.0 or higher (Swift 5.1 is recommended)
• Carthage dependency manager.

Merchant Compliance

Card data should never transit through your server. We recommend that you follow our guide on how to safely collect credit information.

To be authorized to create tokens on your own server, you must have a currently valid PCI-DSS Attestation of Compliance (AoC) delivered by a certified QSA Auditor. This SDK provides means to tokenize card data through the end user's mobile phone without this data having to go through your server.

Installation

To get started, add the following line to your Cartfile:

github "omise/omise-ios" ~> 3.0

Then run carthage bootstrap or carthage build.

Usage

If you cloned this project to your local hard drive, you can also checkout the QuickStart.playground. Otherwise if you'd like all the details, read on:

Omise API

The Omise iOS SDK provides an easy-to-use library for calling the Omise API. The main class for the Omise iOS SDK is Client through which all requests to the Omise API will be sent. Creating a new Client object requires an Omise public key. The SDK currently supports 2 main categories of the requests: Tokenizing a Credit Card and Creating a Payment Source.

Tokenizing a Credit Card

Normally, merchants must not send credit card data to their own servers. So, in order to collect a credit card payment from a customer, merchants will need to tokenize the credit card data using Omise API first and then use the generated token in place of the card data. You can tokenize credit card data by creating and initializing a Request<Token> like so:

let tokenParameter = Token.CreateParameter(
    name: "JOHN DOE",
    number: "4242424242424242",
    expirationMonth: 11,
    expirationYear: 2019,
    securityCode: "123"
)

let request = Request<Token>(parameter: tokenParameter)

Creating a Payment Source

Omise now supports many payment methods other than credit cards. You may request a payment with one of those supported payment methods from a customer by calling CreateSourceParameter API. You need to specify the parameters (e.g. payment amount and currency) of the source you want to create by creating and initializing a Request<Source> with the Payment Information object:

let paymentInformation = PaymentInformation.internetBanking(.bbl) // Bangkok Bank Internet Banking payment method
let sourceParameter = CreateSourceParameter(
    paymentInformation: paymentInformation,
    amount: amount,
    currency: currency
)

let request = Request<Source>(parameter: sourceParameter)

Sending the Request

Whether you are charging a source or a credit card, sending the request is the same. Create a new requestTask on a Client object with the completion handler block and call resume on the requestTask:

let requestTask = client.requestTask(with: request, completionHandler: completionHandler)
requestTask.resume()

You may also send a request by calling the send(_:completionHandler:) method on the Client.

client.send(request) { [weak self] (result) in
  guard let s = self else { return }

  // switch result { }
}

Built-in Forms

Omise iOS SDK provides easy-to-use drop-in UI forms for both Tokenizing a Credit Card and Creating a Payment Source which you can easily integrate into your app.

Credit Card Form

The CreditCardFormViewController provides a pre-made credit card form and will automatically tokenize credit card information for you. You only need to implement two delegate methods and a way to display the form.

Use Credit Card Form in code

To use the controller in your application, modify your view controller with the following additions:

import OmiseSDK // at the top of the file

class ViewController: UIViewController {
  private let publicKey = "pkey_test_123"

  @IBAction func displayCreditCardForm() {
    let creditCardView = CreditCardFormViewController.makeCreditCardFormViewController(withPublicKey: publicKey)
    creditCardView.delegate = self
    creditCardView.handleErrors = true

	present(navigation, animated: true, completion: nil)
  }
}

Then implement the delegate to receive the Token object after user has entered the credit card data:

extension ViewController: CreditCardFormDelegate {
  func creditCardFormViewController(_ controller: CreditCardFormViewController, didSucceedWithToken token: Token) {
    dismissCreditCardForm()

    // Sends `Token` to your server to create a charge, or a customer object.
  }

  func creditCardFormViewController(_ controller: CreditCardFormViewController, didFailWithError error: Error) {
    dismissCreditCardForm()

    // Only important if we set `handleErrors = false`.
    // You can send errors to a logging service, or display them to the user here.
  }
}

Alternatively you can also push the view controller onto a UINavigationController stack like so:

@IBAction func displayCreditCardForm() {
  let creditCardView = CreditCardFormViewController.makeCreditCardFormViewController(publicKey)
  creditCardView.delegate = self
  creditCardView.handleErrors = true

  // This View Controller is already in a UINavigationController stack
  show(creditCardView, sender: self)
}

Use Credit Card Form in Storyboard

CreditCardFormViewController comes with built-in storyboard support. You can use CreditCardFormViewController in your storybard by using Storyboard Reference. Drag the Storyboard Reference object onto your canvas and set its bundle identifier to co.omise.OmiseSDK and Storyboard to OmiseSDK. You can either leave Referenced ID empty or use CreditCardFormController as a Referenced ID You can setup CreditCardFormViewController in UIViewController.prepare(for:sender:) method

override func prepare(for segue: UIStoryboardSegue, sender: Any?) {
  if segue.identifier == "PresentCreditFormWithModal",
    let creditCardFormNavigationController = segue.destination as? UINavigationController,
    let creditCardFormViewController = creditCardFormNavigationController.topViewController as? CreditCardFormViewController {
      creditCardFormViewController.publicKey = publicKey
      creditCardFormViewController.handleErrors = true
      creditCardFormViewController.delegate = self
  }
}

Custom Credit Card Form

You can create your own credit card form if you want to but please keep in mind that you must not send the credit card information to your server. Omise iOS SDK provides some built-in credit card UI components to make it easier to create your own credit card form:

• CardNumberTextField - Provides basic number grouping as the user types.
• CardNameTextField
• CardExpiryDateTextField - Provides card expiration date input and styling
• CardExpiryDatePicker - UIPickerView implementation that has a month and year column.
• CardCVVTextField - CVV number field.

Additionally fields turn red automatically if their content fails basic validation (e.g. alphabetic characters in the number field, content with wrong length, etc.) and come in 2 supported styles, plain and border.

Built-in Payment Creator Controller

The PaymentCreatorController provides a pre-made form to let a customer choose how they want to make a payment. Please note that the PaymentCreatorController is designed to be used as-is. It is a subclass of UINavigationController and you shouldn't push your view controllers into its navigation controller stack. You can configure it to display either specified payment method options or a default list based on your country.

Use Payment Creator Controller in code

You can create a new instance of PaymentCreatorController by calling its factory method:

let allowedPaymentMethods = PaymentCreatorController.thailandDefaultAvailableSourceMethods

let paymentCreatorController = PaymentCreatorController.makePaymentCreatorControllerWith(
  publicKey: publicKey,
  amount: paymentAmount, currency: Currency(code: paymentCurrencyCode),
  allowedPaymentMethods: allowedPaymentMethods,
  paymentDelegate: self
)
present(paymentCreatorController, animated: true, completion: nil)

Then implement the delegate to receive the Payment object after user has selected:

extension ProductDetailViewController: PaymentCreatorControllerDelegate {
  func paymentCreatorController(_ paymentCreatorController: PaymentCreatorController, didCreatePayment payment: Payment) {
    dismissForm()

    // Sends selected `Token` or `Source` to your server to create a charge, or a customer object.
  }

  func paymentCreatorController(_ paymentCreatorController: PaymentCreatorController, didFailWithError error: Error) {
    let alertController = UIAlertController(title: "Error", message: error.localizedDescription, preferredStyle: .alert)
    let okAction = UIAlertAction(title: "OK", style: .cancel, handler: nil)
    alertController.addAction(okAction)
    paymentCreatorController.present(alertController, animated: true, completion: nil)

    // Only important if we set `handleErrors = false`.
    // You can send errors to a logging service, or display them to the user here.
  }

  func paymentCreatorControllerDidCancel(_ paymentCreatorController: PaymentCreatorController) {
  	dismissForm()
  }
}

Use Payment Creator Controller in Storyboard

PaymentCreatorController comes with built-in storyboard support. You can use PaymentCreatorController in your storybard by using Storyboard Reference. Drag Storyboard Reference object onto your canvas and set its bundle identifier to co.omise.OmiseSDK and Storyboard to OmiseSDK and PaymentCreatorController as a Referenced ID You can setup PaymentCreatorController in UIViewController.prepare(for:sender:) method

override func prepare(for segue: UIStoryboardSegue, sender: Any?) {
  if segue.identifier == "PresentCreditFormWithModal",
  let paymentCreatorController = segue.destination as? UINavigationController {
    paymentCreatorController.publicKey = self.publicKey
    paymentCreatorController.paymentAmount = paymentAmount
    paymentCreatorController.paymentCurrency = paymentCurrency
    paymentCreatorController.allowedPaymentMethods = allowedPaymentMethods
    paymentCreatorController.paymentDelegate = self
  }
}

Authorizing Payment

Some payment methods require the customers to authorize the payment via an authorized URL. This includes the 3-D Secure verification, Internet Banking payment, Alipay. The Omise iOS SDK provides a built-in class to do the authorization.

Using built-in Authorizing Payment view controller

You can use the built-in Authorizing Payment view controller by creating an instance of OmiseAuthorizingPaymentViewController and set it with authorized URL given with the charge and expected return URL patterns those were created by merchants.

Create an OmiseAuthorizingPaymentViewController by code

You can create an instance of OmiseAuthorizingPaymentViewController by calling its factory method

let handlerController = OmiseAuthorizingPaymentViewController.makeAuthorizingPaymentViewControllerNavigationWithAuthorizedURL(url, expectedReturnURLPatterns: [expectedReturnURL], delegate: self)
self.present(handlerController, animated: true, completion: nil)

Use OmiseAuthorizingPaymentViewController in Storyboard

OmiseAuthorizingPaymentViewController also comes with built-in storyboard support like CreditCardFormViewController. You can use OmiseAuthorizingPaymentViewController in your storyboard by using Storyboard Reference. Drag Storyboard Reference object onto your canvas and set its bundle identifier to co.omise.OmiseSDK and Storyboard to OmiseSDK then use DefaultAuthorizingPaymentViewController as a Referenced ID. You can setup OmiseAuthorizingPaymentViewController in UIViewController.prepare(for:sender:) method

override func prepare(for segue: UIStoryboardSegue, sender: Any?) {
  if segue.identifier == "AuthorizingPaymentViewController",
    let omiseAuthorizingPaymentController = segue.destination as? OmiseAuthorizingPaymentViewController {
      omiseAuthorizingPaymentController.delegate = self
      omiseAuthorizingPaymentController.authorizedURL = authorizedURL
      omiseAuthorizingPaymentController.expectedReturnURLPatterns =  [ URLComponents(string: "http://www.example.com/orders")! ]
  }
}

Receive Authorizing Payment events via the delegate

OmiseAuthorizingPaymentViewController send Authorizing Payment events to its delegate when there's an event occurred.

extension ViewController: OmiseAuthorizingPaymentViewControllerDelegate {
  func omiseAuthorizingPaymentViewController(_ viewController: OmiseAuthorizingPaymentViewController, didCompleteAuthorizingPaymentWithRedirectedURL redirectedURL: URL) {
    // Handle the `redirected URL` here
  }

  func omiseAuthorizingPaymentViewControllerDidCancel(_ viewController: OmiseAuthorizingPaymentViewController) {
    // Handle the case that user tap cancel button.
  }
}

Objective-C Compatibility

Omise iOS SDK comes with full Objective-C support. The SDK is designed with the Swift language as a first-class citizen and adopts Swift-only features in the SDK, but it also provides an Objective-C counterpart for those features. If you found an API that is not available in Objective-C, please don't hestitate to open an issue.

Migration Note

The Omise iOS SDK provides compatibilty classes to help developers migrate their current code base based on Omise iOS SDK version 2 to the current version 3. The intention is that developer shouldn't have to put much effort into upgrading their code base. The compiler should warn you to rename/change your code to the new API and provide "Fix-it" dialogs for that. However, there are a few exceptions where the SDK and compiler cannot give developer automated "Fix-it" dialogs due to limitations in Swift or compiler itself especially in the Objective-C codebase. We worked with the Swift Open Source Project to fix issues related to Objective-C headers. The fix should be in the Swift 5 compiler.

Omise SDK version 3.1.0 was migrated to adopt Swift 5.0 which introduces the official Result enum value type in Swift starndard library. Omise SDK has adopted the type and replace the existed RequestResult with it and Omise SDK provides the typealias cause which should help on the compatiblity. However due to the Swift syntax limitation, Omise SDK couldn't provide the bridge for fail to Swift.Result.failure case in pattern matching statements. The developer need to migrate this by themselves. We are sorry that this happened but we think this change will pay itself back in the future since the Swift.Result type would be a standard type for representing the Result of an operation.

If you have any questions or problems during your migration, please feel free to post a question in our forum or email our support team.

Note on Version 2.7.0

We encourage merchants to adopt the 3.0.0 version since it introduced many new features including Source API and a built-in Payment Creator form.

To help merchants to adopt the 3.0.0 version, we decided to add version 2.7.0 which is the same one as 3.0.0 and remove the old versions from the releases. The Omise iOS SDK version 3.0.0 comes with the great compatibility with the version 2 this means that merchants should have little work to migrate to the new version. We believe this would help merchants in the long term.

We also highly recommend merchants to fully adopt Omise iOS SDK version 3 to receive the new update in the future.

Contributing

Pull requests, issues, and bugfixes are welcome! For larger changes, please pop on to our forum to discuss first.

LICENSE

MIT See the full license text