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.
- Openpay iOS SDK
- Table of Contents
- Integration
- Examples
- Building
- Features
- Contributing
- License
- iOS 13 or later
- Swift 5.3 or later
- Xcode 12 or later
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.2.0'
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.2.0
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.2.0"))
]
The XCFramework of the Openpay SDK can be generated by following the official documentation.
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 dragOpenpay.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.
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/")!
)
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.
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.
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.
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
}
}
)
}
}
+ (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];
}
struct MainView: View {
@State private var checkoutItem = CheckoutItem(transactionToken: "", handoverURL: "")
var body: View {
SomeCheckoutView()
.openpayWebCheckoutView(checkoutItem: $checkoutItem) { result in
// Handle the checkout result
}
}
}
The Openpay SDK provides two Openpay brandings, openpay
and opy
, which affect the SDK style for UI elements such as payment buttons and badges.
NOTE
An AU or UK merchant should set the SDK branding to openpay
.
A US merchant should set the SDK branding to opy
.
// Set the SDK branding to be `openpay`.
Openpay.setBranding(.openpay)
The Openpay SDK provides several payment buttons you can use to allow people to make payments with Openpay.
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
The button styles below are available in the SDK.
For more details about the payment button see the Openpay SDK Styleguide.
Granite on Amber | Amber on Granite |
---|---|
Granite on White | White on Granite |
---|---|
Maintain the minimum button size around the button in iOS. Use the following values for guidance.
Minimum Width | Maximum Width | Minimum Height |
---|---|---|
218pt | 380pt | 44pt |
For more details about the payment button see the OPY SDK Styleguide.
Granite on Amber | Amber on Granite |
---|---|
Granite on White | White on Granite |
---|---|
Maintain the minimum button size around the button in iOS. Use the following values for guidance.
Minimum Width | Maximum Width | Minimum Height |
---|---|---|
218pt | 380pt | 44pt |
// 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))
The Openpay SDK provides four different color schemes for the badge.
You get the following advantages by using the Openpay badge:
- The badge 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
The following button styles are available in the SDK.
For more details about the badge see the Openpay SDK Styleguide.
Granite on Amber | Amber on Granite | Minimum Width |
---|---|---|
75pt |
The badge is just the Openpay logo and the background is transparent.
White | Granite | Minimum Width |
---|---|---|
80pt |
For more details about the badge see the OPY SDK Styleguide.
Granite on Amber | Amber on Granite | Minimum Width |
---|---|---|
40pt |
The badge is just the Openpay logo and the background is transparent.
White | Granite | Minimum Width |
---|---|---|
34pt |
// 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))
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.
All contributions are welcome! Please refer to our contribution guide before making a submission.
This project is released under the terms of the Apache 2.0 license. See LICENSE file for details.