Integrating with Judopay

We are currently working on updating the Swift sample app.
See our Sample Apps here.



  • You have set up your Judopay account.

    • Sign up for your sandbox account, to receive access to your Judopay dashboard and the sandbox environment.

  • Your judoIds and tokens are configured and enabled as appropriate.

    • For more information on permissions, see Permissions.

  • You have the latest version of the iOS SDK.

For Mobile apps, we recommend using payment session authentication.


Integrating via Swift Package Manager (SPM)

  1. Search for JudoKit-iOS.

  2. Add JudoKit-iOS to your Package Dependencies.


Integrating via CocoaPods

Step One - To integrate the iOS mobile SDK via CocoaPods:

  1. Install CocoaPods with the following command: gem install cocoapods

  2. Via the terminal, navigate to your project's root directory

  3. Initialize CocoaPods with the following command: pod init

  4. A podfile is generated in the root directory


Step Two - To add the mobile SDK as a dependency:

  1. Open the podfile and add the following: pod 'JudoKit-iOS'

  2. Install the dependency with the following command: pod install


The Pod installation complete! message appears in the terminal.

If the Unable to find a specification error message appears, your CocoaPods repository, which stores a reference to all available pods, needs updating.

To update your CocoaPods repository run: $ pod repo update


Ensure you always use the generated .xcworkspace file instead of the .xcodeproj file.


Integrating via Carthage

To integrate the iOS Mobile SDK via Carthage:

  1. Install Carthage on your machine:

    1. Using brew (terminal): brew install carthage

  2. In the root folder of your project, add a new file named Cartfile

  3. In Cartfile, add all the dependencies you need:

    For the purpose of this exercise: github "Judopay/JudoKit-iOS"

  4. In the terminal run the following command: carthage update--use-xcframeworks--platform ios

  5. Check your root folder has the following:

    1. Cartfile.resolved (File with all downloaded dependencies, including their versions)

    2. Carthage folder

  6. In Xcode, manually drag and drop the JudoKit-iOS xcframework and all the dependent xcframeworks into:

    1. Linked Frameworks

    2. Libraries section

      Frameworks are stored in folder Carthage > Build

  1. Rebuild the project

  2. Import the JudoKit-iOS into your project files: #import <JudoKit-iOS/JudoKit_iOS.h>


The iOS Mobile SDK is now ready to use in your iOS project.


Initialising a JudoKit Session

To get started:

  1. To access the JudoKit class, import the JudoKit_iOS framework: #import <JudoKit_iOS/JudoKit_iOS.h>


To initialise a JudoKit session:

  1. Use either a basic (token:secret) authentication method, or a session (token & session) authentication method:

The difference between a basic authentication method and a session authentication method is:
Basic authentications last indefinitely.
Session authentications are valid for one transaction. This offers a more secure authentication approach.

  1. Create a basic authentication instance:

    JPBasicAuthorization *authorization = [JPBasicAuthorization authorizationWithToken:@"token" andSecret:@"secret"]

  1. Create a payment session authentication instance:

    JPSessionAuthorization *authorization = [JPSessionAuthorization authorizationWithToken:@"token" andPaymentSession:@"session token"]


To create a JudoKit session:

JudoKit *judo = [[JudoKit alloc] initWithAuthorization:authorization];

To communicate with the sandbox environment, enter: judo.isSandboxed = YES;

By default, Judopay allows jailbroken devices to access it's features. If you would like to restrict access to non-jailbroken devices only, use this initializer instead: JudoKit *judo = [[JudoKit alloc]initWithAuthorization:authorization "allowJailbrokenDevices:NO];


Setting the Parameters for a Successful Transaction

Use the JPConfiguration object to set the parameters. The JPConfiguration object is passed as a method parameter and communicates how the payment flow should behave.


To configure the JPConfiguration object, add your:

  • JudoId

JudoId format = 100100100

  • Amount

  • ConsumerReference

JPAmount *myAmount;
JPReference *myReference;
JPConfiguration *myConfiguration;

    myAmount = [[JPAmount alloc] initWithAmount:@"0.01"

    myReference = [[JPReference alloc] initWithConsumerReference:@"my-reference"];

    myConfiguration = [JPConfiguration alloc] initWithJudoID:@"my-judo-id"


The JPAmount object sets your:

  • Transaction amount

  • Currency code

The JPReference object sets your reference details, for example your unique consumerReference, to identify your consumer.

Now you can use this object to make a transaction.


Making a Transaction


  1. You have integrated with the Mobile SDK

  2. You have set up the JPConfiguration instance with all the required properties

Card validation | Card formatting | Type | Detection | is handled by Judopay.

If you are using the UI provided with our SDK, see Using the Card Entry UI.

If you are building your own card wallet UI, see Configuring the UI.


The available transaction types that can be passed as a parameter are:

  • Payment

  • PreAuth

  • Register Card

  • Save Card

  • Check Card

For more details, see our Transaction API Reference documentation.

Once you have completed the prerequisite steps, you are ready to make a transaction.


To make a transaction:

  1. Call the method and handle the response from the completion block:

[judo invokeTransactionWithType:TransactionTypePayment
                     completion:^(JPResponse *response, JPError *error) {

     // Handle response / error








An enum value that sets the transaction type.



An object that configures the payment flow.




A completion block that returns the transaction response or an error.


iOS Server to Server Transactions

The SDK also offers server-to-server capabilities. This works by sending the payment token back to the merchant the moment the consumer presses the Pay button.

This allows the merchant to process and complete the transaction on their side.

Server-to-server capabilities are available for both transactions made through:

  • The Payments Widget

  • Apple Pay™

To specify a server-to-server transaction:

  1. Set the TransactionMode to TransactionModeServerToServer when calling the Judopay methods:

[judo invokePaymentMethodScreenWithMode:TransactionModeServerToServer
                             completion:^(JPResponse *response, JPError *error) {
    // Handle the payment token returned from the response


  1. Specify an Apple Pay™ transaction:

[judo invokeApplePayWithMode:TransactionModeServerToServer
                  completion:^(JPResponse *response, JPError *error) {
    // Handle the payment token returned from the response


Token Payments and Preauths

If you are building your own card wallet, and not using a UI you can make a /payments or /preauths transaction using a stored card token.

  1. Follow the steps for Making a Transaction

  2. To make a token transaction:

    1. Call the method and handle the response from the completion block:

[judo invokeTokenTransactionWithType:JPTransactionTypePayment 
                details:cardTransactionDetails completion:^(JPResponse *response, JPError *error) 

    // Handle response / error


3D Secure 2 for iOS

3D Secure 2 is available on Judokit iOS version 3.0.0 or higher, and is available on Github.
(Currently supports Visa and Mastercard. Amex coming soon).

JudoKit-iOS is enabled for 3D Secure 2 (EMV 3DS).


Using the Card Entry UI

The easiest way to integrate 3D Secure is to use the UI within JudoKit, as this handles the 3D Secure flow for you.

Using a 3D Secure Enabled credential*, follow the steps for Making a Transaction.

We recommend using billingAddress and emailAddress fields for 3D Secure 2 transactions.

JPAmount *amount = [[JPAmount alloc] initWithAmount:@"1.50" currency:@"GBP"];
JPReference *reference = [[JPReference alloc] initWithConsumerReference:@"consumer-reference" paymentReference:@"payment-reference"];

JPUIConfiguration *uiConfiguration = [JPUIConfiguration new];

// sets whether 3DS 2.0 UI billing information screen should be presented to the user
uiConfiguration.shouldAskForBillingInformation = YES;

// in case you don't want to present billing info screen to the user, you can set the address instead
JPAddress *address = [[JPAddress alloc] initWithAddress1:@"My house"
                                                address2:@"My street"
                                                address3:@"My area"
                                                    town:@"My town"
                                                postCode:@"TR14 8PA"

JPConfiguration *configuration = [[JPConfiguration alloc] initWithJudoID:@"my-judo-id" amount:amount reference:reference];
configuration.uiConfiguration = uiConfiguration;

configuration.cardAddress = address;

// sets the value for challenge request indicator,
// possible values:
// noPreference
// noChallenge
// challengePreferred
// challengeAsMandate
configuration.challengeRequestIndicator = @"challengeAsMandate";

// sets the value for SCA exemption,
// possible values:
// lowValue
// secureCorporate
// trustedBeneficiary
// transactionRiskAnalysis
configuration.scaExemption = @"lowValue";

// email address
configuration.emailAddress = @"";

// sets the maximum timeout for 3DS 2.0 transactions in minutes,
// always use 2 characters when setting the timeout
configuration.threeDSTwoMaxTimeout = 30;

// sets phone number country code
configuration.phoneCountryCode = @"44";

// phone number
configuration.mobileNumber = @"11223344556677";


Using Token Payments with 3D Secure 2

Using a 3D Secure Enabled credential*, follow the steps for making Token Payments and Preauths.

*Make sure your account has 3D Secure 2 enabled. Contact ​Customer Support​​ to set this up.


Customising your Integration


Adding Payment Methods:

Before you can process Apple Pay™ payments with Judopay, you will need to set up Apple Pay™.



Going Live with iOS

Point to the Live Environment

  1. In ViewController delete the line that specifies the targeted environment: judo.sandboxed = YES;

  1. Replace your sandbox API Token and Secret for the live API Token and Secret 

    Find these in JudopayPortal > Your apps > {app name} > Live Tokens.


Test live payments

Use the live environment for testing before deploying your app.

  • Ensure the SDK is properly configured for the live environment

    • Use real debit or credit cards

      • Test cards provided will not work in live

      • We recommend to perform pre-authorizations followed by a void, or regular payments followed by a refund 

    • Send a refund through the JudopayPortal > History

  • Test all payment scenarios and security features to verify the expected behaviour