Judopay Documentation



iOS Integration with Judopay


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:

    1. 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. To create a basic authentication instance:

    JPBasicAuthorization *authorization = [JPBasicAuthorization authorizationWithToken:
  2. To create a payment session authentication instance:

    JPSessionAuthorization *authorization = [JPSessionAuthorization authorizationWithToken:

To create a JudoKit session:

JudoKit *judo = [[JudoKit alloc] initWithAuthorization:authorization];
  1. 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.

1. 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 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. To 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 optional fields.

yourConsumerReference | yourPaymentReference | amount | currency | judo ID are mandatory fields.

Making a Token Payment or Token Preauth Transaction

To make a token payment or token preauth transaction:

Get the Card Token:

  1. Add the card interface for the consumer to enter their card details:

[judo invokeTransactionWithType:JPTransactionTypeSaveCard
                     completion:^(JPResponse *response, JPError *error) 
           NSString *cardToken = response.cardDetails.cardToken;
            // Save the card token for future use.
  1. As part of the response, you will obtain the card token.

  2. Store the card token to use later.

    This will be added to complete the /payments or /preauths transaction.

Create an API Service Session:

  1. To create the JPApiService instance:

    JPApiService *apiService = [[JPApiService alloc] initWithAuthorization:authorization isSandboxed:

Complete a Token Transaction Request:

  1. To create a JPTokenRequest:

JPTokenRequest *request = [[JPTokenRequest alloc] initWithConfiguration:configuration

Complete a Payments Transaction

  1. Use the JPApiService instance and JPTokenRequest to complete a token payment:

[apiService invokeTokenPaymentWithRequest:request andCompletion:^(JPResponse *response, JPError *error) {
// Handle response

Complete a Preauths Transaction

  1. Use the JPApiService instance and JPTokenRequest to complete a token preauth payment:

[apiService invokePreAuthTokenPaymentWithRequest:request andCompletion:^(JPResponse *response,
// Handle response

Customising the Payment Experience

Configuring the UI

You have flexibility on how the payment experience looks to the consumer.

The JPConfiguration object has a uiConfiguration property of type JPUIConfiguration.

This allows you to:

  • Enable | disable the Address Verification Service 

  • Show | hide the amount in the Payments Widget

  • Show | hide the amount in the payment button

  • Enable | disable consumers entering the CV2 code

  • You can also override some of the default iOS theming options. See iOS Styles and Themes.

An example of the JPUIConfiguration object:

JPUIConfiguration *uiConfig = [JPUIConfiguration new];
    uiConfig.shouldPaymentMethodsDisplayAmount = NO;
    uiConfig.shouldPaymentButtonDisplayAmount: = NO;
    uiConfig.isAVSEnabled = YES;
    uiConfig.shouldPaymentMethodsVerifySecurityCode = YES;

configuration.uiConfiguration = uiConfig;

The JPUIConfiguration instance is set as part of the JPConfiguration object that is passed to our transactions.

Setting the Primary Account Details


To set the primary account details when using an alternative payment method, see Alternative Payment Method Configuration.

To set the primary account details to be sent with the transaction

1. Set the primaryAccountDetails property of the JPConfiguration object:

JPPrimaryAccountDetails *accountDetails;
accountDetails = [JPPrimaryAccountDetails new];

    accountDetails.name = @"example-name";
    accountDetails.accountNumber = @"example-number";
    accountDetails.dateOfBirth = @"example-date";
    accountDetails.postCode = @"example-post-code";

configuration.primaryAccountDetails = accountDetails;

Changing the Default Supported Card Networks

To select the card networks to support:

1. Set the supportedCardNetworks property of the JPConfiguration object with one or more values from this list:

Card Network Name








China Union Pay




Diners Club International







For the purpose of this exercise, Visa and MasterCard are set as the supported card networks: configuration.supportedCardNetworks = CardNetworkVisa | CardNetworkMasterCard;

Setting a Card Address


To set the card address when using an alternative payment method, see Alternative Payment Method Configuration.

To send additional card address details with the transaction:

  1. Set the cardAddress parameter in the JPConfiguration object:

JPAddress *cardAddress = [[JPCardAddress alloc] initWithLine1:@"address-1"
                                                     postCode:@"EX4 MPL3"];


The above properties are optional, so set only the ones you need.

Changing the Default Payment Methods

By default, all payment methods are displayed in the Payments Widget (as long as the required parameters are set). 

You have the flexibility to include the payment methods you support, with pre-defined initialisers for each payment method.


To set the Payment Methods:

1. Set the paymentMethods property in the JPConfiguration object with your list of payment methods:

configuration.paymentMethods = @[  

For the purpose of this exercise, Card and iDEAL transactions are set as the supported payment methods.

The JPPaymentMethod is an object that is initialized by providing a JPPaymentMethodType value.


The order in which you add the payment methods in the array is the order in which they will be displayed on screen.

Alternative Payment Methods


PayByBankApp enables consumers to use bank transfers to easily pay for goods and services online.

For more details on using the PayByBankApp as an alternative payment method, see:


iDEAL enables consumers to easily pay online for goods and services in the Netherlands.

For more details using iDEAL as an alternative payment method, see:

Displaying iDEAL as a Payment Method

To add iDEAL support to your Payments Widget, set:

  1. Currency code to EUR (Euro)

  2. The judoId parameter in the JPConfiguration instance:

An example of a valid iDEAL configuration:

configuration.judoId = @"my-judo-id";

Once the currency and judoId are set, iDEAL will be available as a payment method in the Payments Widget.

Payment Reference and Metadata

You can enable some additional information to be sent within a transaction, for example information to help with reconciliation or receipt tracking. Setting up the paymentReference and metaData properties can allow for:

  • paymentReference

    • a unique payment reference for the transaction.

  • metaData

    • any additional details you require, specific to your organisation or internal sytems.

  1. To pass the paymentReference within the JPReference object with your transaction:

    myReference = [[JPReference alloc] initWithConsumerReference:@"my-reference"
  2. To set the metaData property to send metadata with your transaction:

    myReference.metaData = @{
     		@"my-key": @"my-value"

iOS Styles and Themes

To apply your own custom styles and theme options, override the following payment UI elements:

  1. Initialise the theme object:

    JPTheme *theme = [JPTheme new];

  2. Override the fonts:

    theme.largeTitle = [UIFont systemFontOfSize:20.0f];

    theme.body = [UIFont fontWithName:@"Avenir" size:14.0f];

  1. Override the button properties:

    theme.buttonColor = UIColor.yellowColor;

    theme.buttonTitleColor = UIColor.blackColor;

    theme.buttonCornerRadius = 15.0f;

  2. Set a custom back button image:

    theme.backButtonImage = [UIImage imageNamed:@"my-custom-icon"];

  3. Add the JPTheme instance to the JPUIConfiguration object:

    configuration.uiConfiguration.theme = theme;

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;

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

Find these in Judopay Portal > 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 Judopay Portal > History

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