Before proceeding, please ensure you have met all requirements
Click here to open this information in a new tab
Our GitLab repository includes an example app that demonstrates how to integrate our payment SDK into your application. Click here to view.
Features
The Trust Payments iOS SDK allows you to seamlessly integrate a prebuilt or custom UI in your app to accept card payments & comply with the Strong Customer Authentication (SCA) mandate.
Use this integration if you need a pre-built “Drop-In” UI that supports the following features:
- Card payments
- Tokenization payments
- Customisation of UI components to fit with your business branding
- Locale and custom translations
Otherwise if you have already built your own payment checkout views in your iOS app, but need a method to process payments to the Trust Payments gateway, you can use our payment transaction manager API.
1. Install the SDK in your app
To embed the iOS SDK into your Xcode project, you will need to use one of the following dependency managers:
1. CocoaPods
CocoaPods is a dependency manager for Cocoa projects. For usage and installation instructions, visit their website. To integrate Trust Payments SDK into your Xcode project using CocoaPods, specify it in your Podfile as follows:
pod 'TrustPayments'
2. Carthage
Carthage is a decentralised dependency manager that builds the necessary dependencies and provides you with binary frameworks. To integrate Trust Payments SDK into your Xcode project using Carthage, specify it in your Cartfile as follows:
git "https://gitlab.com/trustpayments-public/mobile-sdk/ios"
Once you have Carthage installed, you can begin adding frameworks to your project. Click here to learn how.
Trust Payments Mobile SDK uses xcframeworks for its dependencies. Make sure you are using Carthage version 0.38 or newer. Then run:
carthage update --platform ios --use-xcframeworks
2. Initialise the iOS SDK in your app
Configure the instance
Before you can perform any payment request, you will need to set the username, gateway and environment, as shown in the example below:
The username is to be stored in a secure location, where only the user with the appropriate privileges can access it. You may wish to consider a similar approach documented for our sample app, whereby we store the username using the cocoapods-keys plugin.
TrustPayments.instance.configure(
username: username_from_trustpayments,
gateway: .eu,
environment: .staging,
translationsForOverride: nil
)
View controllers
The following is an example of how to create a Drop-In View Controller using only the required fields:
let dropInVC = try ViewControllerFactory.shared.dropInViewController(
jwt: jwt,
payButtonTappedClosureBeforeTransaction: {
(controller: DropInController) in
},
transactionResponseClosure: {
(
jwt: [String],
transactionResult: TPAdditionalTransactionResult?,
error: APIClientError?
)
in
}
)
Parameter | Description | |
Optional | cardinalDarkModeStyleManager | Specifies light/dark mode for the ACS view (3-D Secure). |
Optional | cardinalStyleManager | Specifies interface style for the ACS view (3-D Secure). |
Optional | customDropInView | DropInViewProtocol compliant view for additional views, e.g. for adding a tip to a payment. |
Optional | dropInViewDarkModeStyleManager | Specifies light/dark mode for the Drop-In View Controller. |
Optional | dropInViewStyleManager | Used to customise the Drop-In View Controller. |
Required | jwt |
The signed JWT. |
Required | payButtonTappedClosureBeforeTransaction |
Closure triggered by pressing the pay button (just before the transaction – you can use this closure to update the JWT token) You can use this closure to update the JWT token by calling the updateJWT() function on the controller that is passed as an argument. |
Required | transactionResponseClosure |
Closure triggered when the transaction is completed, with the following properties:
|
You can customise UI components in the Drop-In View Controller to fit your business branding.
Click here to open instructions in a new tab.
Card Input Fields
As an alternative to our Drop-In View Controller, we offer integrators an option to create individual card components for PAN, expiry date and security code. You can include these components on your pre-existing payment checkout view controller as shown below:
lazy var cardNumberInput: CardNumberInputView = {
CardNumberInputView(inputViewStyleManager: inputViewStyleManager)
}()
lazy var expiryDateInput: ExpiryDateInputView = {
ExpiryDateInputView(inputViewStyleManager: inputViewStyleManager)
}()
lazy var cvvInput: CVVInputView = {
CVVInputView(inputViewStyleManager: inputViewStyleManager)
}()
Then listen for CardNumberInput delegate method and adjust the security code to reflect the required number of digits for the given card:
extension SingleInputView: CardNumberInputViewDelegate {
func cardNumberInputViewDidComplete(_ cardNumberInputView: CardNumberInputView) {
cvvInput.cardType = cardNumberInputView.cardType
cvvInput.isEnabled = cardNumberInputView.isCVVRequired
}
func cardNumberInputViewDidChangeText(_ cardNumberInputView: CardNumberInputView) {
cvvInput.cardType = cardNumberInputView.cardType
cvvInput.isEnabled = cardNumberInputView.isCVVRequired
}
}
Once the customer has clicked the pay button, you will need to create an instance of our SDKs paymentTransactionManager and call the performTransaction method, as shown in the next step.
Payment Transaction Manager
If you intend to use our individual card components, as mentioned above or already have / intend to build your own payment checkout card inputs, but need a method to process payments to the Trust Payments gateway, you can use our transaction manager API.
You can review our example app to see first hand how to configure the Payment Transaction Manager.
let paymentTransactionManager = try PaymentTransactionManager(jwt: .empty)
paymentTransactionManager.performTransaction(jwt: jwt, card: card, transactionResponseClosure: {jwt, transactionResult, error in})
Once you create an instance of the paymentTransactionManager, you will be able to call its performTransaction method to make a payment request. You need to be aware of the following parameters when calling performTransaction:
Required | jwt |
The signed JWT created on your server, whose payload should contain all the details related to the transaction e.g. billing, shipping, amount, order reference, etc. |
Required | card |
The card object is created from within the app, and contains the pan, expiry date and security code e.g.
|
Required | transactionResponseClosure |
Closure triggered when the transaction is completed, with the following properties:
|
3. Configure webhooks
It is strongly recommended that you configure webhooks on your Mobile SDK solution. When configured, URL notifications are sent to your system when payments are processed on your account.
If you do not configure webhooks as explained below, you may not be notified of payments processed on your account, e.g. in cases of client-side errors that occur prior to the response being returned.
- Sign in to Portal.
- Search for your sitereference using the search box found at the top of the page.
- When viewing your site details, click “Rule manager“.
- Select the action type “URL notification” from the drop-down and your browser will be redirected.
- Create a new URL notification rule:
- (A) Click “Add new condition” and specify the circumstances in which the URL notification is to be triggered following a transaction. In the Requests box displayed, ensure “AUTH” is ticked (meaning the notification is triggered following payment authorisations).
Click here to learn more about configuring conditions. - (B) Click “Add new action” and specify the endpoint for the URL notification.
Click here to learn more about URL notification actions. - (C) Using the drop-down boxes, assign the condition to the action and click “Create rule“.
- (A) Click “Add new condition” and specify the circumstances in which the URL notification is to be triggered following a transaction. In the Requests box displayed, ensure “AUTH” is ticked (meaning the notification is triggered following payment authorisations).
- Ensure the rule is active (this is shown with a tick under the Active column). Once enabled, the rule will be applied to all payment sessions for the given sitereference, and the URL notification will be triggered whenever the condition specified is met.
Note: All new rules should be created on your test sitereference and tested to ensure they work as expected before being added to your live sitereference.
-
You must configure your system to respond to all URL notifications received from Trust Payments with an HTTP 200 OK response.
For example: “HTTP/1.0 200 OK”.
Your system must reply within 8 seconds of receiving a notification.
Once you have completed the steps above, we recommend returning to the Getting started page to learn more about enabling add-ons, testing your solution and going live.