iOS

Integrating iOS with Judopay
We are currently working on updating the Swift sample app.
See our Sample Apps here.
Prerequisites
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)
Search for JudoKit-iOS.﻿
Add JudoKit-iOS to your Package Dependencies.
﻿
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
Ensure you always use the generated .xcworkspace file instead of the .xcodeproj file.
﻿
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--use-xcframeworks--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 xcframework and all the dependent xcframeworks into:
Linked Frameworks
Libraries section
Frameworks are stored in folder Carthage > Build
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 JudoKit_iOS framework:
#import <JudoKit_iOS/JudoKit_iOS.h>
To initialise a JudoKit session:
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.
Use either a basic (token:secret) authentication method, or a session (token & session) authentication method.
Create a basic authentication instance:
JPBasicAuthorization *authorization = [JPBasicAuthorization authorizationWithToken:@"token" andSecret:@"secret"]
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"
 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
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
Prerequisites
You have integrated with the Mobile SDK﻿﻿
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
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:
Call the method and handle the response from the completion block:
[judo invokeTransactionWithType:TransactionTypePayment
 configuration:configuration
 completion:^(JPResponse *response, JPError *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
JPError
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:
Server to Server Example
//Set the TransactionMode to TransactionModeServerToServer when calling the Judopay methods:

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

//Specify an Apple Pay™ transaction:

[judo invokeApplePayWithMode:TransactionModeServerToServer
               configuration:configuration
                  completion:^(JPResponse *response, JPError *error) {
    // Handle the payment token returned from the response
}];
//Set the TransactionMode to TransactionModeServerToServer when calling the Judopay methods:

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

//Specify an Apple Pay™ transaction:

[judo invokeApplePayWithMode:TransactionModeServerToServer
               configuration:configuration
                  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.
Follow the steps for Making a Transaction﻿﻿
To make a token transaction:
Token Transaction Request
//Call the method and handle the response from the completion block:

[judo invokeTokenTransactionWithType:JPTransactionTypePayment 
                configuration:configuration 
                details:cardTransactionDetails completion:^(JPResponse *response, JPError *error) 
{ 
    // Handle response / error
}];
//Call the method and handle the response from the completion block:

[judo invokeTokenTransactionWithType:JPTransactionTypePayment 
                configuration:configuration 
                details:cardTransactionDetails completion:^(JPResponse *response, JPError *error) 
{ 
    // Handle response / error
}];
﻿
﻿
3D Secure 2 for iOS
JudoKit-iOS is enabled for 3D Secure 2 (EMV 3DS).
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). 
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.
Card Entry UI
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"
                                                    town:@"My town"
                                          billingCountry:@"826"
                                                postCode:@"TR14 8PA"
                                             countryCode:@826];

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 = @"[email protected]";

// 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";
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"
                                                    town:@"My town"
                                          billingCountry:@"826"
                                                postCode:@"TR14 8PA"
                                             countryCode:@826];

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 = @"email@me.com";

// 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﻿.
﻿
﻿
Customising your Integration
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
Enable | disable consumers entering the cardholder name
Enable | disable consumers entering the billing information
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.shouldAskForCSC = YES;
 uiConfig.shouldAskForCardholderName = YES;
 uiConfig.shouldAskForBillingInformation = YES;

configuration.uiConfiguration = uiConfig;
The JPUIConfiguration instance is set as part of the JPConfiguration object that is passed to our transactions.
 
The incremental authorisation feature allows you to increment the value of your original preAuth for scenarios where you need to charge your customer a higher total amount.
By incrementing the preAuth value, you will be able to capture the total amount that you wish to charge your customer when you are ready.
The allowIncrement flag allows you to set up your initial preAuth so that it can be incremented by an additional amount.
This feature is only available with a limited set of processors - please check with your account manager before you use this feature.
isAllowIncrement is a part of the main JPConfiguration config object, and can be set directly during configuration setup.
If present = it is automatically applied for pre-auth requests.
If no value is provided = then false is set by default.
Example:
JPConfiguration *configuration = [[JPConfiguration alloc] initWith …];
(...)
configuration.isAllowIncrement = YES;
﻿
It is mandatory for merchants who have an MCC code of 6012 to submit additional Information about the primary account holder in primaryAccountDetails property for payment pre-authorisation.
To set the primary account details when using an alternative payment method, see Adding Payment Methods﻿.
To set the primary account details to be sent with the transaction:
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;
﻿
To select the card networks to support:
Set the supportedCardNetworks property of the JPConfiguration object with one or more values from this list:
Card Network Name
Value
Visa
JPCardNetworkTypeVisa
MasterCard
JPCardNetworkTypeMasterCard
Maestro
JPCardNetworkTypeMaestro
AMEX
JPCardNetworkTypeAMEX
China Union Pay
JPCardNetworkTypeChinaUnionPay
JCB
JPCardNetworkTypeJCB
Diners Club International
JPCardNetworkTypeDinersClub
Discover
JPCardNetworkTypeDiscover
All
JPCardNetworkTypeAll
For the purpose of this exercise, Visa and MasterCard are set as the supported card networks:
configuration.supportedCardNetworks = JPCardNetworkTypeVisa | JPCardNetworkTypeMasterCard;
﻿
To set the card address when using an alternative payment method, see Adding Payment Methods﻿.
To send additional card address details with the transaction:
Set the cardAddress parameter in the JPConfiguration object:
JPAddress *cardAddress = [[JPCardAddress alloc] initWithAddress1:@"address-1"
 address2:@"address-2"
 town:@"example-town"
 postCode:@"EX4 MPL3" 
 countryCode:@"GB"
 state:nil
];
 The above properties are optional, so set only the ones you need.
  
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:
Set the paymentMethods property in the JPConfiguration object with your list of payment methods:
configuration.paymentMethods = JPPaymentMethodCard | JPPaymentMethodIDeal;
For the purpose of this exercise, Card and iDEAL transactions are set as the supported payment methods.
You can:
Add any language you need.
Override some or all of the translations of an existing language.
The Judokit iOS SDK supports: en (default), fr, es.
Generally, language translations follows the iOS localisation process, utilising ".lproj directories" and Localizable.strings files.
Use Existing Translations
To use or test one of Judopay's default language translations, change the language on your iOS device:
Settings → General → Language & Region → iPhone Language
The translation will be applied automatically.
﻿
Override Existing Translations
Identify the SDK String Keys.
The SDK uses string resources defined in its Localizable.strings file. 
You can find the list of all String Keys below.
To modify the value of an existing string, add a new one with the same key to the Localizable.strings file in your iOS project. 
This will override the SDK value of this string,
If your app supports multiple languages, ensure you add translations for the overridden string in the corresponding .lproj directories.
For example: fr.lproj for French, es.lproj for Spanish. 
Also, remember to declare any new language in "Project > Info > Localizations". This will ensure the translation is recognised by the framework.
﻿
To add a new language
Identify the SDK String Keys and prepare the translations for all values in the language you wish to add or override.
You can find the list of all String Keys below.
In your app’s project directory, create a new .lproj folder for the language you want to add. 
Ensure you use the correct language and region codes. 
For example:
es.lproj for Spanish
zh-Hans.lproj for Simplified Chinese.
Inside the new language folder, create a Localizable.strings file if one does not already exist.
Within the newly created Localizable.strings file ensure you provide the translations for all String Keys used by the SDK, otherwise the translation may end up incomplete.
Declare the new language in: "Project > Info > Localizations".
This will ensure the translation is recognised by the framework.
When overriding or adding new String Keys, be careful to avoid String Key conflicts between the SDK and your app.
Any matching Key will cause your app’s value to override the SDK's default value, which could potentially lead to unintended behaviour, or mismatched translations.
﻿
SDK String Keys:

"add_card" = "Add card";
"apple_pay" = "Apple Pay";
"button_done" = "DONE";
"button_edit" = "Edit";
"button_scan_card" = "Scan card";
"button_add_address_line_card" = "+ Add address line (optional)";
"cancel" = "Cancel";
"back" = "Back";
"card_holder_email_hint" = "Email";
"card_holder_hint" = "Cardholder Name";
"card_holder_country_hint" = "Country";
"card_holder_state_hint" = "State";
"card_holder_province_hint" = "Province or territory";
"card_holder_phone_hint" = "Mobile number";
"card_holder_city_hint" = "City";
"card_holder_adress_line_hint" = "Address line";
"card_number_hint" = "Card Number";
"card_subtitle" = "Ending";
"cards" = "Cards";
"check_card" = "Check Card";
"check_expiry_date" = "Check expiry date";
"choose_payment_method" = "Choose a Payment Method";
"connected_cards" = "Connected cards";
"country_canada" = "Canada";
"country_other" = "Other";
"country_uk" = "UK";
"country_usa" = "USA";
"customize_card" = "Customise Card";
"default_amex_card_title" = "My American Express Card";
"default_chinaunionpay_card_title" = "My China Union Pay Card";
"default_dinersclub_card_title" = "My Diners Club Card";
"default_discover_card_title" = "My Discover Card";
"default_jcb_card_title" = "My JCB Card";
"default_maestro_card_title" = "My Maestro Card";
"default_mastercard_card_title" = "My MasterCard Card";
"default_visa_card_title" = "My VISA Card";
"delete" = "Delete";
"delete_card_alert_message" = "Are you sure you want to delete this card from your wallet?";
"delete_card_alert_title" = "Delete Card?";
"dismiss" = "Dismiss";
"error" = "Error";
"enter_card_title" = "Enter a card title...";
"error_card_title_too_long" = "Card Name cannot be longer than 28 characters";
"error_invalid_card_number_desc" = "Invalid card number";
"error_unsupported_card_desc" = "%@ is not supported";
"expire_soon" = "Expire soon";
"expired" = "Expired";
"expiry_date" = "MM/YY";
"ideal_payment" = "iDeal";
"ideal_transaction" = "iDEAL Transaction";
"invalid_expiry_date_value" = "Invalid date value entered";
"invalid_email_value" = "Invalid email entered";
"invalid_phone_code_value" = "Invalid phone code entered";
"invalid_phone_value" = "Invalid phone entered";
"invalid_postcode" = "Invalid postcode entered";
"invalid_zip_code" = "Invalid ZIP code entered";
"invalid_email_address" = "Please enter a valid email";
"invalid_state_should_not_be_empty" = "Please select a state";
"invalid_province_territory_should_not_be_empty" = "Please select a province or territory";
"invalid_address" = "Please enter a valid address";
"invalid_mobile_number" = "Please enter a valid mobile number";
"invalid_city" = "Please enter a valid city";
"is_expired" = "Is expired";
"no_cards_added" = "You didn’t add any cards yet. Add one right now or use any of the payment methods below";
"no_connected_cards" = "You didn't connect any cards yet";
"ok" = "Ok";
"pay_amount" = "Pay %@";
"pay_now" = "Pay Now";
"continue" = "Continue";
"post_code_hint" = "Postcode";
"email_hint" = "Email";
"phone_country_code_hint" = "+()";
"mobile_number_hint" = "Mobile number";
"address_line_1_hint" = "Address line 1";
"address_line_2_hint" = "Address line 2";
"address_line_3_hint" = "Address line 3";
"city_hint" = "City";
"processing" = "Transaction pending...";
"register_card" = "Register Card";
"retry" = "Retry";
"save" = "Save";
"save_as_default_payment_method" = "Save as default payment method";
"save_card" = "Save Card";
"scan_card_confirm" = "Got it";
"scan_card_go_to_settings" = "Go to Settings";
"scan_card_hint_subtitle" = "We will do our best to scan it";
"scan_card_hint_title" = "Position card in this frame";
"scan_card_no_permission_message" = "Permissions must be granted in order to use the scan card functionality. Please go to Settings and toggle Camera on";
"scan_card_no_permission_title" = "Camera permissions not granted";
"scan_card_restricted_message" = "Scan camera functionality is not available due to restriction on your device";
"scan_card_restricted_title" = "Camera access restricted";
"scan_card_simulator_title" = "Camera not available on iOS simulators";
"secure_server_transmission" = "Your card details are encrypted using TLS before transmission to our secure payment service provider.";
"three_d_secure_check" = "3D Secure Check";
"transaction_delayed" = "This is taking longer than expected...";
"transaction_successful" = "Transaction success!";
"transaction_timeout" = "Transaction timed out!";
"transaction_unsuccessful" = "Card transaction unsuccessful - please try again";
"unknown_card_network" = "Unknown card network";
"will_expire_soon" = "It will expire soon";
"you_will_pay" = "You will pay";
"error_invalid_ideal_currency_desc" = "iDEAL transactions only support EUR as the currency.";
"error_invalid_ideal_currency_reason" = "Invalid currency passed to iDEAL transaction configuration.";
"error_apple_pay_not_supported_desc" = "Apple Pay is not supported on this device.";
"error_apple_pay_not_supported_reason" = "An Apple Pay transaction was attempted on a device that either does not support, or does not have Apple Pay set up.";
"error_request_failed_desc" = "The request has failed or responded without data.";
"error_request_failed_reason" = "The transaction response returned without any data or there was an error while forming the request.";
"error_request_timeout_desc" = "The request has timed out.";
"error_request_timeout_reason" = "The request failed to complete in the allocated time frame.";
"error_json_serialization_desc" = "The response data could not be serialized into a JSON.";
"error_json_serialization_reason" = "The server responded with an invalid data format.";
"error_user_cancelled_desc" = "The transaction was cancelled by the user.";
"error_user_cancelled_reason" = "The user closed the transaction flow without completing the transaction.";
"error_internet_connection_desc" = "No internet connection found.";
"error_internet_connection_reason" = "The request could not be sent due to no internet connection.";
"error_invalid_card_number_reason" = "The number entered is not a valid card number or is not supported by the SDK.";
"error_unsupported_card_reason" = "The number entered belongs to a card network that is not allowed by the merchant.";
"error_response_parse_desc" = "Unexpected response format returned.";
"error_response_parse_reason" = "The response did not contain some of the required parameters needed to complete the transaction.";
"error_no_message_desc" = "The request has failed with no underlying message.";
"error_no_message_reason" = "The server responded with an error.";
"error_apple_pay_missing_items_desc" = "The Apple Pay configuration must have at least one payment item.";
"error_apple_pay_missing_items_reason" = "The Payment Items array of the Apple Pay configuration is either empty or missing.";
"error_apple_pay_missing_shipping_desc" = "The Apple Pay configuration must have at least one shipping method.";
"error_apple_pay_missing_shipping_reason" = "Shipping methods must be set if the required shipping contact fields are specified.";
"error_judo_id_missing_desc" = "The Judo ID parameter cannot be null or empty.";
"error_judo_id_missing_reason" = "The required Judo ID parameter has not been set in the Judo configuration.";
"error_invalid_judo_id_desc" = "The Judo ID entered is invalid.";
"error_invalid_judo_id_reason" = "The specified Judo ID parameter has an incorrect format.";
"error_currency_missing_desc" = "Currency cannot be null or empty.";
"error_currency_missing_reason" = "The required Currency parameter has not been set in the Judo configuration.";
"error_invalid_currency_desc" = "The specified currency code is not supported.";
"error_invalid_currency_reason" = "The currency code entered is either not a valid ISO 4217 code or is not supported by the SDK.";
"error_apple_pay_merchant_id_missing_desc" = "The Apple Pay merchant ID cannot be null or empty.";
"error_apple_pay_merchant_id_missing_reason" = "Apple Pay needs a valid merchant ID to be able to identify your transaction.";
"error_invalid_country_code_desc" = "The specified country code is not supported.";
"error_invalid_country_code_reason" = "The country code entered is either not a valid ISO 3166 2-letter code or is not supported by the SDK.";
"error_apple_pay_config_missing_desc" = "The Apple Pay transaction has not been configured.";
"error_apple_pay_config_missing_reason" = "No Apple Pay configuration was found in your Judo configuration object.";
"error_invalid_amount_desc" = "The amount specified should be a positive number.";
"error_invalid_amount_reason" = "The amount parameter has either not been set or has an incorrect format.";
"error_invalid_consumer_ref_desc" = "The consumer reference entered is invalid.";
"error_invalid_consumer_ref_reason" = "The consumer reference parameter has either not been set or has an incorrect format.";
"error_invalid_token_payment_transaction_type_desc" = "Token payments transactions only support JPTransactionTypePayment and JPTransactionTypePreAuth as the transaction type.";
"error_invalid_token_payment_transaction_type_reason" = "Invalid transaction type passed to token payment transaction configuration.";
"error_preauth_properties_conflict_desc" = "Both delayedAuthorisation and allowIncrement flags can't be set to true.";
"error_preauth_properties_conflict_reason" = "Preauth properties conflict";
"error_recommendation_server_prevented_transaction_desc" = "The recommendation server has prevented this transaction.";
"error_recommendation_server_prevented_transaction_reason" = "It appears that the transaction you attempted to make has been blocked by the recommendation server.";
"error_recommendation_server_request_failed_desc" = "There was an error when retrieving the recommendation response.";
"error_recommendation_server_request_failed_reason" = "We are unable to process this request as there was an error when retrieving the recommendation response.";
"error_recommendation_invalid_authorization_type_desc" = "Payment session is required for using the recommendation feature.";
"error_recommendation_invalid_authorization_type_reason" = "To use the recommendation feature, it is mandatory to have a payment session.";
"error_recommendation_invalid_URL_desc" = "The URL field in the recommendation configuration is required.";
"error_recommendation_invalid_URL_reason" = "It is mandatory to provide a URL in the recommendation configuration.";
"error_recommendation_invalid_rsa_public_key_desc" = "The RSAPublicKey field in the recommendation configuration is required.";
"error_recommendation_invalid_rsa_public_key_reason" = "It is mandatory to provide a RSAPublicKey in the recommendation configuration.";
"error_recommendation_invalid_timeout_desc" = "The timeout value provided in the recommendation configuration must be a number.";
"error_recommendation_invalid_timeout_reason" = "The timeout in the recommendation configuration should be an instance of NSNumber.";
"error_missing_recurring_description_desc" = "Recurring Payment description cannot be null";
"error_missing_recurring_description_reason" = "The required Recurring Payment parameter has not been set in the Apple Pay configuration.";
"error_missing_recurring_management_url_desc" = "Recurring Payment management URL cannot be null";
"error_missing_recurring_management_url_reason" = "The required Recurring Payment parameter has not been set in the Apple Pay configuration.";
"error_missing_recurring_regular_billing_desc" = "Recurring Payment regular billing cannot be null";
"error_missing_recurring_regular_billing_reason" = "The required Recurring Payment configuration sub-object is missing.";
"error_missing_recurring_amount_desc" = "Recurring Payment amount cannot be null";
"error_missing_recurring_amount_reason" = "The required Recurring Payment parameter has not been set in the Apple Pay configuration.";
"error_missing_recurring_label_desc" = "Recurring Payment label cannot be null";
"error_missing_recurring_label_reason" = "The required Recurring Payment parameter has not been set in the Apple Pay configuration.";
"continue_text" = "Continue";
"add_address_line" = "Add address line (optional)";
"billing_details_title" = "Billing Details";
"back" = "Back";
"card_holder_name_required" = "Cardholder Name is required";
"card_holder_name_too_short" = "Cardholder Name can't be less than 4 characters";
"card_holder_name_special_chars" = "Cardholder Name can't contain numbers or special characters";
"check_security_code" = "Check your ";
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;
﻿
﻿
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:
unique payment reference for the transaction.
metaData:
Any additional details you require, specific to your organisation or internal systems.
Set up paymentReference and metaData Properties
//Pass the paymentReference within the JPReference object with your transaction:

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

//Set the metaData property to send metadata with your transaction:

myReference.metaData = @{
   @"my-key": @"my-value"
}
//Pass the paymentReference within the JPReference object with your transaction:

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

//Set the metaData property to send metadata with your transaction:

myReference.metaData = @{
   @"my-key": @"my-value"
}
﻿
﻿
﻿
Adding Payment Methods
Before you can process Apple Pay™ payments with Judopay, you will need to set up Apple Pay™.
Apple Pay™ is not supported on all Apple devices.

Before invoking any Apple Pay™ functionality within your app, test if it is supported on the device by performing these checks:
Use PKPaymentAuthorizationViewController canMakePayments
Checks if the device supports Apple Pay™ and has it enabled.
Queries both the device hardware and whether Apple Pay™ is enabled in the user’s region
Use PKPaymentAuthorizationViewController canMakePaymentsUsingNetworks
A more detailed check to query whether a user has a registered card with particular card schemes.
Useful if you do not accept all card types.
Both methods are explained in the Apple developer documentation here.
﻿

Getting Your Apple Pay™ Account
System Requirements:

A compatible Apple device: iPhone 6 & 6 Plus | iPad Air 2 | iPad mini 3 | or newer
iOS 12.0 or newer
Xcode 14.0 or newer

﻿
Create a Merchant ID
We recommend creating a Merchant ID for each Merchant (i.e. business) accepting payments within your app.

To set up your Apple Pay™ account:
﻿
1
Access your Apple Developer Account.
Navigate to Certificates, Identifiers & Profiles.
2
From the side menu, click Merchant IDs.
3
In the iOS Merchant ID Settings screen, click the add button.
4
Set your Merchant ID.
The identifier you enter should be a reverse DNS style identifier prefixed with the word.
5
Click Done.
﻿

Create an Apple Pay™ Certificate
 
Prerequisite
Request a Certificate Signing Request (CSR) file from Judopay.
When you’ve received your CSR, you can create your Apple Pay™ certificate.
 
To create your Apple Pay™ certificate:
﻿
1
From the side menu, select either:

Certificates > All
Merchant ID
2
The screen appears describing how to manually create your Certificate Signing Request (CSR).
As you’ve already obtained your CSR from Judopay, click Continue.
3
You will be prompted to state if you are processing transactions outside the United States.
Select No.
4
Click Continue.
5
Click Choose File to upload the CSR file provided by Judopay.
6
Click Generate.
7
The confirmation screen appears.
Your certificate is ready to download.
Click Download.
8
Click Done.
To complete your Apple Pay™ set-up send the certificate to Judopay.
Once received, we will add the certificate to your account and confirm it has been added.
Apple Certificates expire just over two years after generation. 
For example a certificate generated on 13th May 2024 will expire on the 11th June 2025.
Refer to your Apple Developer Account for an accurate expiry date.
To generate a new certificate follow the steps above.
﻿


Set Up Apple Pay™ Entitlement
Apple Pay™ is built into the PassKit framework, which means you will need to configure the entitlement.
 
To set up the entitlement:
﻿
1
Select your build Target.
2
Select Capabilities.
3
Set the entitlement to Enabled.
4
Add the Merchant ID created earlier to the app.
You may need to refresh the list.
5
Open the entitlements file to confirm the Merchant ID has been added to your app.
Your account is now ready to process Apple Pay™ payments with Judopay. 
Configure the  iOS Mobile SDK ﻿ to start making payments.
﻿
Apple Pay™ Button
 
Apple Pay™ allows the consumer to:

Bypass the standard checkout flow
Complete their payment with speed
﻿
When integrating with Apple Pay™, it is recommended to consider when to introduce the Apple Pay™ button.
This can be:

On a single item product listing page
Within a basket page with multiple items
Both of the above scenarios
The Apple Pay™ button enables consumers to make a purchase from the specific page they are browsing.
By tapping the Apple Pay™ button, the payment sheet is invoked to begin the checkout process.
 
For more information on the Apple Pay™ button, see Apple’s guidance of the PKPaymentButton Class Reference.
﻿

Best Practice Testing
You can test Apple Pay™ in the sandbox environment with the sandbox cards, however please note these test transactions will not work going upstream.
To test Apple Pay™ transactions, point to the live environment and use live cards.

We recommend performing | Pre-Authorizations | Card Payments | Full Refunds: via the Judopay Dashboard > History, or via an API call


We strongly recommend testing Apple Pay™ through each of these scenarios before you release the app:

Unsupported Device
Use a non-supported device in order to verify the whole recognition workflow works as expected.
Card not Supported
Use a card issued by a bank that does not support Apple Pay™. You can also use the test cards provided on the Judopay Dashboard to validate the error returned and expected behaviour.
Payment Cancelled
Cancel a transaction in process and see the results in the app and in your Judopay Dashboard history.
Poor / Loss of Connection
While a transaction is being processed, disconnect the internet connection to see if the app responds as expected.
To configure Apple Pay™:
Add the Apple Pay™ configuration
Call the Apple Pay™ method
Step One: Adding the Apple Pay™ Configuration
All Judo transactions require a JPConfiguration instance passed as a method parameter.
The basic JPConfiguration requires:
Judo ID
Amount
Consumer reference
Apple Pay™ transactions require additional parameters in order to work correctly.
To set all the Apple Pay™ required parameters, use the JPApplePayConfiguration:
NSDecimalNumber *itemOnePrice = [NSDecimalNumber decimalNumberWithString:@"649.99"];
NSDecimalNumber *itemTwoPrice = [NSDecimalNumber decimalNumberWithString:@"55.00"];
NSDecimalNumber *totalPrice = [NSDecimalNumber decimalNumberWithString:@"704.99"];

NSArray *mySummaryItems = @[ 
[JPPaymentSummaryItem itemWithLabel:@"iPhone XR 254GB" amount:itemOnePrice], 
[JPPaymentSummaryItem itemWithLabel:@"iPhone XR Case" amount:itemTwoPrice], 
[JPPaymentSummaryItem itemWithLabel:@"Apple Store" amount:totalPrice],
];
For each item you wish to list, you will need to sum up the item in the basket.
Payment summary items:
This is a list of JPPaymentSummaryItem objects, that describe the item being purchased, including the price. 
In the example above, the item label was set to the merchant from where the item was purchased.
This is how the JPApplePayConfiguration looks:
NSArray *mySummaryItems

JPApplePayConfiguration *applePayConfig;
applePayConfig = [[JPApplePayConfiguration alloc] initWithMerchantId:@"my-merchant-id"
 currency:@"GBP" 
countryCode:@"GB" 
paymentSummaryItems:mySummaryItems
];

Parameter
﻿
Description
 
merchantId
NSString
Your Apple Pay™ merchant ID.This confirms you are able to accept payments.
currency
NSString
An ISO 4217 currency code.
countryCode
NSString
An ISO 3166-1 Alpha-2 country code.
paymentSummaryItems
NSArray
The list of items.
The last item in the array should always represent the total amount.
Step Two - Add the instance to the object
Add the JPApplePayConfiguration instance to the JPConfiguration object:
configuration.applePayConfiguration = applePayConfig;
Call the Judo method
Invoke Apple Pay™ by providing the TransactionMode
This allows you to select:
Payment or,
PreAuth
Set the Apple Pay™ configuration:
[judo invokeApplePayWithMode:TransactionModePayment 
configuration:myApplePayConfiguration 
completion:^(JPResponse *response, JPError *error) { 
// Handle response or error
}];
To display Apple Pay™ as a payment method:
Configure the JPApplePayConfiguration object
From the JPConfiguration already created, call:
[[judo invokePaymentMethodScreenWithMode:TransactionModePayment 
configuration:configuration 
completion:^(JPResponse *response, JPError *error) {
// Handle the response and error
}];
In the example, the TransactionMode is set as the first method parameter. 
﻿
Adding the Billing and Shipping Details
If you would like the consumer to provide their billing and shipping details, set the following properties:
requiredBillingContactFields 
requiredShippingContactFields
You can choose between multiple contact field types:
email address 
phone number 
post code
For example:
applePayConfig.requiredBillingContactFields = JPContactFieldName | JPContactFieldEmail;
applePayConfig.requiredShippingContactFields = JPContactFieldAll;
Parameter
Description
JPContactFieldName
Consumer's name.
JPContactFieldEmail
Consumer's valid email address.
JPContactFieldPhone
Consumer's valid phone number.
JPContactFieldPostalAddress
Consumer's postal address.
JPContactFieldAll
All the values above.
If you set shipping details as a required field, you must also set the shippingType and the shippingMethods properties. 
To set the shipping type:
applePayConfig.shippingType = JPShippingTypeDelivery;
Parameter
Description
JPShippingTypeShipping
Shipping.
The default value.
JPShippingTypeDelivery
Delivery.
JPShippingTypeStorePickup
Store Pickup.
JPShippingTypeServicePickup
Service Pickup.
Setting the shipping methods requires an array of PaymentShippingMethod objects.

To set an array of paymentShippingMethod objects:
NSDecimalNumber *deliveryCost = [NSDecimalNumber decimalNumberWithString:@"25.0"];

PaymentShippingMethod *delivery;
delivery = [[PaymentShippingMethod alloc] initWithIdentifier:@"delivery" 
detail:@"Deliver to your address" 
label:@"Delivery" 
amount:deliveryCost];
applePayConfig.shippingMethods = @[delivery];
﻿
Getting the Billing and Shipping Details
To get the billing and shipping information back from the consumer:
Set the returnedContactInfo:
applePayConfig.returnedContactInfo = ReturnedInfoBillingContacts;
Parameter
Description
JPReturnedInfoBillingContacts
Billing details returned.
The default value.
JPReturnedInfoShippingContacts
Shipping details returned.
JPReturnedInfoAll
Billing and Shipping details returned.
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.
﻿
﻿
Going Live with iOS
Point to the Live Environment
In ViewController delete the line that specifies the targeted environment: judo.sandboxed = YES;
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
﻿
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
Follow our suggested guidelines to simulate both positive / happy path scenarios, and negative scenarios in the sandbox environment to test your integration is working correctly.
This will give you confidence for when your integration goes live.
See:
﻿Testing iOS SDK - Card Payments﻿﻿
﻿Testing Apple Pay™ Wallet - via Mobile SDK﻿﻿
﻿
Name	Type	Description
type	TransactionType	An enum value that sets the transaction type.
configuration	JPConfiguration	An object that configures the payment flow.
completion	JPResponse JPError	A completion block that returns the transaction response or an error.
Card Network Name	Value
Visa	JPCardNetworkTypeVisa
MasterCard	JPCardNetworkTypeMasterCard
Maestro	JPCardNetworkTypeMaestro
AMEX	JPCardNetworkTypeAMEX
China Union Pay	JPCardNetworkTypeChinaUnionPay
JCB	JPCardNetworkTypeJCB
Diners Club International	JPCardNetworkTypeDinersClub
Discover	JPCardNetworkTypeDiscover
All	JPCardNetworkTypeAll
Parameter	Description
merchantId NSString	Your Apple Pay™ merchant ID.This confirms you are able to accept payments.
currency NSString	An ISO 4217 currency code.
countryCode NSString	An ISO 3166-1 Alpha-2 country code.
paymentSummaryItems NSArray	The list of items.
Parameter	Description
JPContactFieldName	Consumer's name.
JPContactFieldEmail	Consumer's valid email address.
JPContactFieldPhone	Consumer's valid phone number.
JPContactFieldPostalAddress	Consumer's postal address.
JPContactFieldAll	All the values above.
Parameter	Description
JPShippingTypeShipping	Shipping. The default value.
JPShippingTypeDelivery	Delivery.
JPShippingTypeStorePickup	Store Pickup.
JPShippingTypeServicePickup	Service Pickup.
Parameter	Description
JPReturnedInfoBillingContacts	Billing details returned. The default value.
JPReturnedInfoShippingContacts	Shipping details returned.
JPReturnedInfoAll	Billing and Shipping details returned.
Updated 07 Oct 2024
Android
React Native
iOS

Integrating iOS with Judopay

Prerequisites

Integrating via Swift Package Manager (SPM)

Integrating via CocoaPods

Integrating via Carthage

Initialising a JudoKit Session

Setting the Parameters for a Successful Transaction

Making a Transaction

Prerequisites

iOS Server to Server Transactions

Token Payments and Preauths

3D Secure 2 for iOS

Using the Card Entry UI

Using Token Payments with 3D Secure 2

Customising your Integration

UI Configuration

Setting up an Incremental Authorisation

Setting the Primary Account Details

Changing the Default Supported Card Networks

Setting a Card Address

Changing the Default Payment Methods

Adding a New Language

iOS Styles and Themes

Payment Reference and MetaData

Adding Payment Methods

Setting up Apple Pay for iOS

Configuring Apple Pay for iOS

Displaying Apple Pay for iOS

Integrating iDEAL for iOS

Going Live with iOS

Point to the Live Environment

Test live payments
