Judopay Documentation

iOS

PreRequisites

iOS Integration with Judopay

Tip

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

Caution

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

 

Tip

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. Provide your apps token and secret: JudoKit *judo = [[JudoKit alloc] initWithToken:"my-token" secret:"my-secret"];

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];

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

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

  • Amount

  • ConsumerReference

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

    myAmount = [[JPAmount alloc] initWithAmount:@"0.01"
                                   currency:@"GBP"];

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

    myConfiguration = [JPConfiguration alloc] initWithJudoID:@"my-judo-id"
                                       amount:myAmount
                                               reference:myReference];

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

Prerequisites:

  1. You have integrated with the Mobile SDK

  2. You have setup the JPConfiguration instance with all the required properties

Note

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
                  configuration:configuration
                     completion:^(JPResponse *response, NSError *error) {

     // Handle response / error

}];

Name

Type

Description

type

TransactionType

An enum value that sets the transaction type.

configuration

JPConfiguration

An object that configures the payment flow.

completion

JPResponse

NSError

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
                                         configuration:configuration
                                            completion:^(JPResponse *response, NSError *error) {
    // Handle the payment token returned from the response
}];
  1. To specify an Apple Pay™ transaction:

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

Token Payments

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

Steps:

  1. Use the TokenPayment or TokenPreAuth endpoints

  2. Create a function

  3. Create the Card Token and Secret

  4. Send a Json Request

  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

To make a token payment or preauth token payment:

  1. Initialise the JPTransactionService with the card token and secret.

  2. Create the JPTransaction object from the transactionService and configuration object:

  JPTransactionService *transactionService = [[JPTransactionService alloc] initWithToken:@"token_string"
                                                                                 andSecret:@"secret_string"];

    JPTransaction *transaction = [transactionService transactionWithConfiguration:self.configuration];
  1. Update the transaction with your card token:

self.transaction.cardToken = @"your_card_token";
  1. Handle the response:

 [self.transactionService payWithTransaction:self.transaction andCompletion:^(JPResponse *response, JPError *error) {
        [weakSelf handleResponse:response error:error];
    }];

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

Note

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

Value

Visa

CardNetworkVisa

MasterCard

CardNetworkMasterCard

AMEX

CardNetworkAMEX

China Union Pay

CardNetworkChinaUnionPay

JCB

CardNetworkJCB

Discover

CardNetworkDiscover

Diners Club

CardNetworkDinersClub

All

CardNetworksAll

 

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

Setting a Card Address

Note

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"
                                                        line2:@"address-2"
                                                        line3:nil
                                                         town:@"example-town"
                                                  countryCode:@"GB"
                                                     postCode:@"EX4 MPL3"];

Tip

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 = @[  
    JPPaymentMethod.card,  
    JPPaymentMethod.iDeal
];

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.

Note

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

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

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"
                                                paymentReference:@"my-payment-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