Getting started with iOS SDK

  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.


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.

  Click here to learn more.




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:


  Please note

Apple M1

One of our binary dependencies is not Apple M1 ready yet, therefore running the TrustPayments SDK on M1 using native simulators is not currently supported. If you wish to use native simulators, please run your Xcode and Terminal using Rosetta.


Since the arm64 architecture for simulators is missing, it has to be excluded in the build settings. See Podfile for how this is done when using Cocoapods. If you are using Carthage, please use the prepared script.


1. CocoaPods

CocoaPods is a dependency manager for Cocoa projects. For usage and installation instructions, visit their website. To integrate Trust Payments into your Xcode project using CocoaPods, specify it in your Podfile as follows:

# Includes all modules
pod 'TrustPayments', :git => '', :branch => 'master'

# Includes specific modules of interest
pod 'TrustPayments/Core' # Performing transactions using your own views
pod 'TrustPayments/UI' # Performing transactions with a ready-to-use “drop-in” controller
pod 'TrustPayments/Card' # Module with useful methods to validate card data


2. Carthage

Carthage is a decentralised dependency manager that builds the necessary dependencies and provides you with binary frameworks. To integrate Trust Payments into your Xcode project using Carthage, specify it in your Cartfile as follows:

git ""

Once you have Carthage installed, you can begin adding frameworks to your project. Click here to learn how.

  If you have problems installing to Xcode versions 12 and 13 via Carthage, we have provided an installation script to assist you.

Click here to download from our GitLab repository.

Paste the script into your project and run the following command:

./ update –platform iOS




2. Initialise the iOS SDK in your app


Configure the instance

Before you can perform any payment request, you will need to set the usernamegateway and environment, as shown in the example below:

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],
threeDResponse: ThreeDResponse?,
error: APIClientError?
  Parameter Description
table-optional.png cardinalDarkModeStyleManager Specifies light/dark mode for the ACS view (3-D Secure).
table-optional.png cardinalStyleManager Specifies interface style for the ACS view (3-D Secure).
table-optional.png customDropInView DropInViewProtocol compliant view for additional views, e.g. for adding a tip to a payment.
table-optional.png dropInViewDarkModeStyleManager Specifies light/dark mode for the Drop-In View Controller.
table-optional.png dropInViewStyleManager Used to customise the Drop-In View Controller.
table-required.png jwt

The signed JWT.

Click here to learn how generate the JWT.

table-required.png 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.

table-required.png transactionResponseClosure Closure triggered when the transaction is completed, with the following properties:
  • JWT key array with responses from all requests (the signature of each key should be verified before decoding).
  • An object that contains 3-D Secure authentication data sent with the AUTH request.
  • An error object indicating if there were errors in connecting to the gateway server or during 3-D Secure authentication.

The following is an alternative example of how to create a Drop-In View Controller containing more optional parameters:

let dropInVC = try ViewControllerFactory.shared.dropInViewController(

jwt: jwt,
customDropInView: dropInCustomView,
visibleFields: [.securityCode3],
dropInViewStyleManager: dropInViewStyleManager,
dropInViewDarkModeStyleManager: dropInViewDarkModeStyleManager,
cardinalStyleManager: cardinalStyleManager,
cardinalDarkModeStyleManager: cardinalDarkModeStyleManager,

payButtonTappedClosureBeforeTransaction: {
controller: DropInController

transactionResponseClosure: {
jwt: [String],
threeDResponse: ThreeDResponse?,
error: APIClientError?


  You can customise UI components in the Drop-In View Controller or ACS interface (3-D Secure).
Click here to open instructions in a new tab.


Plain card input field

The below demonstrates how to create card detail input views without performing any requests on your behalf:

Creating separate UI components:

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 required number of digits for 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


Payment Transaction Manager

If you already have / intend to build 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 transaction manager API.

  You can review our example app for examples on how to configure the Payment Transaction Manager.

let paymentTransactionManager = try PaymentTransactionManager(jwt: .empty)

paymentTransactionManager.performTransaction(jwt: jwt, card: card, transactionResponseClosure: {jwt, threeDResponse, error in})

As part of this process, the payment card fields, panexpirydate and securitycode will be captured on your custom payment form and added to the JSON Web Token (JWT) payload. To learn how to construct the JWT, click here to open more info in a new tab.

If you specify the fields panexpirydate and securitycode inside of the JWT payload created on your merchant server, then the same JWT (including card details) provided during initialisation will be passed back in the response from the gateway inside the field jwt.

Ensure any sensitive payment credentials (pan, expirydate and securitycode) are sanitized prior to logging to your system.




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.

  1. Sign in to MyST.

  2. Search for your sitereference using the search box found at the top of the page.

  3. When viewing your site details, click “Rule manager“.


  4. Select the action type “URL notification” from the drop-down and your browser will be redirected.


  5. 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“.


  6. 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.

  7. 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.

Click here to open the Getting started page.


Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request