Integrating with Judopay


  • You have set up your Judopay account.

  • You have the latest version of the iOS SDK.

For Mobile apps, it is recommended not to make a transaction from the app, as the Token and Secret could become compromised. Use the server to make the transaction.
Create a Register Card app and enable the Register Card Transactions permission.


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.


See Judopay's JudoKit for iOS on Github.


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 --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 framework and all the dependent frameworks into:

    1. Linked Frameworks

    2. Libraries section

      Frameworks are stored in folder Carthage > Checkouts > Carthage/Builds

  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 JudoKitObjC  framework: #import <JudoKitObjC/JudoKitObjC.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:

  1. Create a payment session authentication instance:

    JPSessionAuthorization *authorization = [JPSessionAuthorization authorizationWithToken:


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]initWithToken:"my-token" secret:"my-secret"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

  • JPReference

These are used to set 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 setup the JPConfiguration instance with all the required properties

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



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 handling the response from the completion block:

[judo invokeTransactionWithType:TransactionTypePayment
                     completion:^(JPResponse *response, NSError *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:

[self.judoKitSession invokePaymentMethodScreenWithMode:TransactionModeServerToServer
                completion:^(JPResponse *response, NSError *error) {
    // Handle the payment token returned from the response


  1. Specify an Apple Pay™ transaction:

[self.judoKitSession invokeApplePayWithMode:TransactionModeServerToServer
            completion:^(JPResponse *response, NSError *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. Create the Card Token

  2. Create an API Service Session

  3. Create a Token Transaction Request

  4. Make a transaction using the /payments or /preauths endpoint

  5. Handle the Response


Billing Address | primary account details | CV2 are


yourConsumerReference | yourPaymentReference | amount | currency | judo ID are



3D Secure 2 for iOS

3D Secure 2 is available on Judokit iOS version 3.0.0 or higher, and is available on Github.
You can use the latest SDK for 3D Secure 1. (Currently supports Visa and Mastercard. Amex coming soon).

JudoKit-iOS is enabled for both 3D Secure 1 and 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: self.judoKitSession.apiSession.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

    self.judoKitSession = [[JudoKit alloc] initWithToken:token secret:secret];


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