Openpay iOS SDK

The Openpay SDK for iOS allows you to integrate Openpay with ease. It provides a framework and documentation for developers to enable payments for customers.

Table of Contents

• Openpay iOS SDK
• Table of Contents
• Integration
  • Requirements
  • CocoaPods
  • Carthage
  • Swift Package Manager
  • Manually
    • XCFramework
    • Git Submodule
• Examples
• Building
  • Mint
• Features
  • Web Checkout View
    • Swift - UIKit
    • Objective-C
    • SwiftUI
  • Openpay Payment Button
    • Amber with Granite Grey
    • Granite Grey with White
    • Example
  • Openpay Badge
    • Amber with Granite Grey
    • Light
    • Example
  • Themes
• Contributing
• License

Integration

Requirements

• iOS 13 or later
• Swift 5.3 or later
• Xcode 12 or later

CocoaPods

CocoaPods is a dependency manager for Swift and Objective-C Cocoa projects. For installation and usage instructions, please visit their website for details. To integrate the Openpay SDK into your Xcode project using CocoaPods, add it to your Podfile:

pod 'Openpay', '~> 0.1.0'

Carthage

Carthage is a dependency manager that builds your dependencies to provide you with binary frameworks. To integrate the Openpay SDK into your Xcode project using Carthage, add it to your Cartfile:

github "openpay-innovations/sdk-ios" ~> 0.1.0

Swift Package Manager

The Swift Package Manager is a tool for managing the distribution of Swift code.

NOTE

When you add the SDK from Xcode -> File -> Swift Packages -> Add Package Dependency and select the version you want, Xcode will automatically suggest the current version Up to Next Major.

We strongly suggest that while the iOS Openpay SDK is on a 0.x.y version scheme, you should select Up to Next Minor, because we will still be releasing breaking changes on minor versions.

To integrate Openpay SDK into your Xcode project using SPM, add it to your Package.swift:

dependencies: [
    .package(url: "https://github.com/openpay-innovations/sdk-ios.git", .upToNextMinor(from: "0.1.0"))
]

Manually

XCFramework

The XCFramework of the Openpay SDK can be generated by following the official documentation.

Git Submodule

Follow the steps below to add the Openpay SDK as a git submodule:

• Navigate to the root of your working directory

• Run the command to add the SDK as a submodule

  git submodule add https://github.com/openpay-innovations/sdk-ios.git Openpay
  

• Open the new Openpay folder and drag Openpay.xcodeproj into the Project Navigator of your application's Xcode project.

• Select Openpay.xcodeproj in the Project Navigator and make sure that the deployment target matches that of your application target.

• Select your application project and navigate to the target configuration window.

• Select the application target under the "Targets" heading in the sidebar.

• Open the "General" panel in the tab bar at the top of that window.

• Click on the + button under the "Frameworks, Libraries, and Embedded Content" section.

• Select Openpay.framework.

That's all you need to import the Openpay SDK and you can now build it on the device and simulator.

Examples

The example project gives an example of how the payment flow works with the web checkout.

To run the example app, open Openpay.xcworkspace and the example project can be built and run via the Example target.

NOTE

To be able to see the web checkout view, you need to provide the order ID, transaction token and the base handover URL in Configuration.swift. The order ID, transaction token and handover URL can be obtained via the merchant server calling the Openpay create order endpoint.

/// Insert your order Id, transaction token and handover URL to see the web checkout view.
let createOrderResponse = CreateOrderResponse(
    orderId: "",
    transactionToken: "",
    handoverURL: URL(string: "https://example.com/")!
)

Building

Mint

Mint is a package manager that installs and runs Swift command line tool packages. The Openpay SDK uses Mint to install and run the packages listed in the Mintfile such as SwiftLint.

You can simply build the SDK project with Cmd + B or run the bootstrap-tools script to install all the Swift command line tool packages before the first build to speed up the build time.

You do not need to install Mint manually as an extra step because a pre-compiled Mint executable file is included under the directory Tools/mint.

Features

Web Checkout View

The web checkout view can be modally presented, passing the URL-encoded transaction token and the base handover URL. When the web checkout flow is completed, the web view will be dismissed and return the checkout result.

Check our demo: Web Checkout Sample Video

The transaction token and the base handover URL are generated via the /orders endpoint on the Openpay backend. Note that the transaction token returned from the Openpay backend is already URL-encoded so you do not need to encode it again.

Swift - UIKit

    final class CheckoutViewController: UIViewController {
        private func presentCheckoutWebView(transactionToken: String, handoverURL: URL) {
            Openpay.presentWebCheckoutView(
                over: self,
                transactionToken: transactionToken,
                handoverURL: handoverURL,
                completion: { result in
                    switch result {
                    case .success(.webLodged(let planId, _)):
                        // Handle the successful result
                    case .failure(let failure):
                        // Handle the failure result
                    }
                }
            )
        }
    }

Objective-C

  + (void)presentWebCheckoutViewOverViewController:(UIViewController *)viewController
                                  transactionToken:(NSString *)token
                                       handoverURL:(NSURL *)url
                                          animated:(BOOL)flag
                                  webLodgedHandler:(WebLodgedHandler)webLodgedHandler {

      void (^completion)(OPWebCheckoutResult *) = ^(OPWebCheckoutResult *result) {
          OPSuccess *success = [(OPWebCheckoutResultSuccess *)result status];

          // Handle the successful result
          if ([success isKindOfClass:[OPWebLodged class]]) {
              OPWebLodged *webLodged = (OPWebLodged *)success;
              webLodgedHandler([webLodged planId], [webLodged orderId]);
              return;
          }

          OPFailure *failure = [(OPWebCheckoutResultFailure *)result status];
          // Handle different types of failure
          if ([failure isKindOfClass:[OPWebCancelled class]]) {
              OPWebCancelled *webCancelled = (OPWebCancelled *)failure;
              webCancelledHandler([webCancelled planId], [webCancelled orderId]);
              return;
          }
          ...
      };
      [OPOpenpay presentWebCheckoutViewOverViewController:viewController
                                         transactionToken:token
                                              handoverURL:url
                                                 animated:flag
                                               completion:completion];
  }

SwiftUI

    struct MainView: View {
        @State private var checkoutItem = CheckoutItem(transactionToken: "", handoverURL: "")
        var body: View {
          SomeCheckoutView()
          .openpayWebCheckoutView(checkoutItem: $checkoutItem) { result in
              // Handle the checkout result
          }
        }
    }

Openpay Payment Button

The Openpay SDK provides several payment buttons you can use to allow people to make payments with Openpay. The button styles below are available in the SDK.

For more details about the payment button see SDK Styleguide.

Amber with Granite Grey

Granite on Amber	Amber on Granite

Granite Grey with White

Granite on White	White on Granite

Maintain the minimum button size around the button in iOS. Use the following values for guidance.

You get the following advantages by using the Openpay payment button:

• Support for configuring the button’s corner radius to match the style of your UI
• Support for accessibility label that lets VoiceOver describe the button
• Support for light and dark modes
• Adjust the corner radius to match the appearance of other buttons in your app

Example

// Initialize an Openpay checkout button using graniteOnAmber theme in light mode and amberOnGranite theme in dark mode.
// The OpenpayPaymentButton is a subclass of UIButton
let checkoutButton = OpenpayPaymentButton(theme: .dynamic(light: .graniteOnAmber, dark: .amberOnGranite))

Openpay Badge

The Openpay SDK provides four different color schemes for the badge view. The following button styles are available in the SDK.

For more details about the badge see SDK Styleguide.

Amber with Granite Grey

Granite on Amber	Amber on Granite	Minimum Width
		75pt

Light

The badge is just the Openpay logo and the background is transparent.

White	Granite	Minimum Width
		80pt

You get the following advantages by using the Openpay badge:

• The badge view can be scaled to to match the style of your UI
• Support for accessibility label that lets VoiceOver describe the badge
• Support for light and dark modes

Example

// Initialize an Openpay badge using graniteOnAmber color scheme in light mode and amberOnGranite color scheme in dark mode.
// The OpenpayBadge is a subclass of UIView
let openpayBadge = OpenpayBadge(theme: .dynamic(light: .graniteOnAmber, dark: .amberOnGranite))

Themes

The Openpay SDK allow developers to apply different color schemes for different user interfaces. The following themes are available in the SDK:

• Universal

  The universal theme uses a static color scheme and does not adapt to light and dark interfaces.

• Dynamic

  The dynamic theme adapts to light and dark interfaces.

Contributing

All contributions are welcome! Please refer to our contribution guide before making a submission.

License

This project is released under the terms of the Apache 2.0 license. See LICENSE file for details.