iOS
PreRequisites
You have set up your Judopay account.
You have the latest version of the iOS SDK.
For more details, see iOS Integration with Judopay.
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:
Install CocoaPods with the following command:
gem install cocoapods
Via the terminal, navigate to your project's root directory
Initialize CocoaPods with the following command:
pod init
A podfile is generated in the root directory
Step Two - To add the mobile SDK as a dependency:
Open the podfile and add the following:
pod 'JudoKit-iOS'
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:
Install Carthage on your machine:
Using brew (terminal): brew install carthage
In the root folder of your project, add a new file named Cartfile
In Cartfile, add all the dependencies you need:
For the purpose of this exercise: github "Judopay/JudoKit-iOS"
In the terminal run the following command:
carthage update --platform iOS
Check your root folder has the following:
Cartfile.resolved (File with all downloaded dependencies, including their versions)
Carthage folder
In Xcode, manually drag and drop the JudoKit-iOS framework and all the dependent frameworks into:
Linked Frameworks
Libraries section
Frameworks are stored in folder Carthage > Checkouts > Carthage/Builds
Rebuild the project
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:
To access the JudoKit class, import the JudoKitObjC framework:
#import <JudoKitObjC/JudoKitObjC.h>
To initialise a JudoKit session:
Use either a basic (token:secret) authentication method, or a session (token & session) authentication method:
Note
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.
To create a basic authentication instance:
JPBasicAuthorization *authorization = [JPBasicAuthorization authorizationWithToken:
To 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;
Tip
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
Note
JudoId format = 100100100
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:
You have integrated with the Mobile SDK
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 |
---|---|---|
| TransactionType | An enum value that sets the transaction type. |
| JPConfiguration | An object that configures the payment flow. |
| 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:
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 }];
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 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.
Steps:
Create the Card Token
Create an API Service Session
Create a Token Transaction Request
Make a transaction using the
/payments
or/preauths
endpointHandle 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:
Add the card interface for the consumer to enter their card details:
[judo invokeTransactionWithType:JPTransactionTypeSaveCard configuration:configuration completion:^(JPResponse *response, JPError *error) { NSString *cardToken = response.cardDetails.cardToken; // Save the card token for future use. }];
As part of the response, you will obtain the card token.
Store the card token to use later.
This will be added to complete the
/payments
or/preauths
transaction.
Create an API Service Session:
To create the JPApiService instance:
JPApiService *apiService = [[JPApiService alloc] initWithAuthorization:authorization isSandboxed:
Complete a Token Transaction Request:
To create a JPTokenRequest:
JPTokenRequest *request = [[JPTokenRequest alloc] initWithConfiguration:configuration andCardToken:@"YOUR_TOKEN"
Complete a Payments Transaction
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
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
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:
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:
Mobile:
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:
Mobile:
Displaying iDEAL as a Payment Method
To add iDEAL support to your Payments Widget, set:
Currency code to EUR (Euro)
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.
To pass the paymentReference within the JPReference object with your transaction:
myReference = [[JPReference alloc] initWithConsumerReference:@"my-reference" paymentReference:@"my-payment-reference"];
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:
Initialise the theme object:
JPTheme *theme = [JPTheme new];
Override the fonts:
theme.largeTitle = [UIFont systemFontOfSize:20.0f];
theme.body = [UIFont fontWithName:@"Avenir" size:14.0f];
Override the button properties:
theme.buttonColor = UIColor.yellowColor;
theme.buttonTitleColor = UIColor.blackColor;
theme.buttonCornerRadius = 15.0f;
Set a custom back button image:
theme.backButtonImage = [UIImage imageNamed:@"my-custom-icon"];
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