iOS

UI Configuration

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.

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.

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.

Primary Account Details

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:

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;

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:

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

Card Address

To set the card address when using an alternative payment method, see Adding Payment Methods:

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

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

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.

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

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

3. Override the button properties:

   theme.buttonColor = UIColor.yellowColor;

   theme.buttonTitleColor = UIColor.blackColor;

   theme.buttonCornerRadius = 15.0f;

4. Set a custom back button image: theme.backButtonImage = [UIImage imageNamed:@"my-custom-icon"];

5. Add the JPTheme instance to the JPUIConfiguration object: configuration.uiConfiguration.theme = theme;

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. Pass the paymentReference within the JPReference object with your transaction:

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

2. Set the metaData property to send metadata with your transaction:

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

Setting Up Apple Pay™ for iOS

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:

Create an Apple Pay™ Certificate

Pre-Requisite:

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:

Apple Certificates expire just over two years after generation. For example a certificate generated on 13th May 2022 will expire on the 11th June 2023.
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:

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.

   

Configuring Apple Pay for iOS

To configure Apple Pay™:

1. Add the Apple Pay™ configuration

2. 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.

1. 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.

NSArray *mySummaryItems

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

merchantId

currency

countryCode

paymentSummaryItems

The last item in the array should always represent the total amount.

Step Two - Add the instance to the object

1. Add the JPApplePayConfiguration instance to the JPConfiguration object: configuration.applePayConfiguration = applePayConfig;

2. Call the Judo method

3. Invoke Apple Pay™ by providing the TransactionMode

   This allows you to select

   • Payment or,

   • PreAuth

4. Set the Apple Pay™ configuration:

[judo invokeApplePayWithMode:TransactionModePayment               
    configuration:myApplePayConfiguration                  
    completion:^(JPResponse *response, NSError *error) {    
    // Handle response or error
}];

Display Apple Pay as a Payment Method for iOS

To display Apple Pay™ as a payment method:

1. Configure the JPApplePayConfiguration object

2. From the JPConfiguration already created, call:

[self.judoKitSession invokePaymentMethodScreenWithMode:TransactionModePayment     
        configuration:configuration                                            
        completion:^(JPResponse *response, NSError *error) {
// Handle the response and error
}];

In the example, the TransactionMode  is set as the first method parameter. 
This is an enum value that allows the selection between Payment and PreAuth transactions.

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

applePayConfig.requiredBillingContactFields = ContactFieldName | ContactFieldEmail;
applePayConfig.requiredShippingContactFields = ContactFieldAll;

ContactFieldName

ContactFieldEmail

ContactFieldPhone

ContactFieldPostalAddress

ContactFieldAll

 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 = ShippingTypeDelivery;

ShippingTypeShipping

ShippingTypeDelivery

ShippingTypeStorePickup

ShippingTypeServicePickup

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;

ReturnedInfoBillingContacts

ReturnedInfoShippingContacts

ReturnedInfoAll

Displaying PayByBankApp as a Payment Method for iOS

To display the PayByBankApp as a Payment Method for iOS:

1. In the info.plist of app and LSApplicationQueriesSchemes add the URL scheme of the merchant(CFBundleURLSchemes)::

<key>CFBundleURLTypes</key>
    <array>
        <dict>
            <key>CFBundleTypeRole</key>
            <string>Editor</string>
            <key>CFBundleURLSchemes</key>
            <array>
                <string>judo</string>
            </array>
        </dict>
    </array>
    <key>LSApplicationQueriesSchemes</key>
    <array>
        <string>zapp</string>
    </array>

3. Add deeplink to the pbbaConfiguration object:

  self.pbbaConfig = [JPPBBAConfiguration new];
  self.pbbaConfig.deeplinkScheme = @"judo://pay";

4. To enable the PayByBankApp set the following options:

   1. Add the pbba method to:

      The paymentMethods  array in JPConfiguration

   2. Set currency:

      GBP

Not using the Mobile SDK Payments Widget?

To Integrate directly to your app:

Prerequisites

• "Bank3 Test App" - Contact: developersupport@judopayments.com to get access, so you can test the PayByBankApp flow.

• You have set your app's URL Scheme.

• You have added zapp to the ApplicationQueriesSchemes:

An example of the Info.plist file:

Step 1: Initialising the SDK

To integrate with the Judopay SDK directly to your iOS app, you can use either a:

• basic authorization

  This uses a token and secret

• session authorization

  This uses a token and paymentSession

You can select the sandbox mode for testing purposes.

Set the value:isSandboxed = true

let authorization: JPAuthorization = JPBasicAuthorization(token: JUDO_TOKEN,
  andSecret: JUDO_SECRET)
        judoKit = JudoKit(authorization: authorization)
        judoKit.isSandboxed = true

Step 2: Check for Installed Bank Apps

To ensure a good customer experience, it is recommended to only display the PayByBankApp button when the consumer has a compatible mobile Banking app.

Before adding the PayByBankApp button in Step 3, check if any compatible PayByBankApp Bank apps are installed, using the JudoKit isBankingAppAvailable  method:

if (JudoKit.isBankingAppAvailable()) {
    // Add the PBBA button
}

Step 3: Adding the PayByBankApp Button

We recommend you use the branded button to invoke a PayByBankApp transaction, however it is not mandatory.

The PayByBankApp Button uses the delegate property.

The delegate property points to any class that implements the JPPBBAButtonDelegate interface:

let pbbaButton = JPPBBAButton(frame: container.bounds);
    pbbaButton.delegate = self
        view.addSubview(pbbaButton)

The JPBBAButton is a subclass of UIView, not UIButton.

Take this into consideration when integrating the PayByBankApp button via the Interface Builder.

The JPPBBAButtonDelegate interface has only one method: pbbaButtonDidPress(sender:), which is responsible for handling the button tap action.

Recommended PayByBankApp Button Size:

• Minimum: Width 160pt | Height 40pt

• Maximum: Width 310pt | Height 48pt

Step 4: Adding the Delegate Method

The delegate method is responsible for the button tap action.

To add the delegate method:

1. Call the invokePBBA method in the Judopay SDK and provide the required configuration parameters:

func pbbaButtonDidPress(_ sender: JPPBBAButton) {

    let amount = JPAmount(AMOUNT_VALUE, currency: "GBP")
    let reference = JPReference(consumerReference: CONSUMER_REF)

    configuration = JPConfiguration(judoID: JUDO_ID, amount: amount, reference: reference)

    let pbbaConfiguration = JPPBBAConfiguration()
    pbbaConfiguration.mobileNumber = YOUR_MOBILE_NUMBER
    pbbaConfiguration.emailAddress = YOUR_EMAIL_ADDRESS
    pbbaConfiguration.appearsOnStatement = YOUR_APPEARS_ON_STATEMENT
    pbbaConfiguration.deeplinkScheme = YOUR_DEEPLINK_SCHEME

    configuration.pbbaConfiguration = pbbaConfiguration

    judoKit.invokePBBA(with: configuration) { [weak self] (response, error) in
        if let response = response {
            // Handle response
        }

        if let error = error {
            // Handle error
        }
    }
}

• Each Judopay transaction takes a JPConfiguration instance as a parameter.The configuration object sets up all the required parameters for a successful transaction. It also sets any optional parameters which you can configure to personalise the payment flow.

• PayByBankApp transactions require some extra parameters to be set up, in addition to the basic transaction configuration. These optional parameters are defined in the JPPBBAConfiguration class, and used to add additional information to the transaction. The following two parameters are recommended:

  • deeplinkScheme

  • deeplinkURL

• Call the invokePBBA method from the Judopay SDK.

The PayByBankApp flow will be triggered, opening the Bank app for consumers to make their transactions.

For more details, see Step 5: Handling the deeplinkURL.

It is a good idea to handle the errors within this step.

The most important information from the response is the orderId, accessed via response.orderDetails.orderId.

The orderId is used to manually check the transaction status.

For more details, see Manually Checking the Transaction Status.

Step 5: Handling the deeplinkURL

Following the completed transaction, the bank flow will be triggered when the invokePBBA method is called, even if the deeplinkURL parameter is not provided.

However, if the deeplinkURL parameter is provided, calling invokePBBA will trigger the transaction status polling logic.

To handle the deeplinkURL:

1. Listen to this event.

2. Capture the redirect URL.

To capture the redirect URL:

• In your AppDelegate file, add the following methods:

  • application(_:open:options:)

  • application(_:didFinishLaunchingWithOptions:)

func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {

     if let url = launchOptions?[.url] as? URL {
         UserDefaults.standard.set(url, forKey: "deeplinkURL")
     }

     ...
}

func application(
    _ app: UIApplication, open url: URL,
    options: [UIApplication.OpenURLOptionsKey : Any] = [:]
    ) -> Bool {

     UserDefaults.standard.set(url, forKey: "deeplinkURL")

     ...
}

3. Pass the URL to the JPPBBAConfiguration instance.

For the purpose of this exercise, the deeplinkURL is saved in the app's UserDefaults.

You can save the deeplinkURL in the Keychain or any alternative.

Step 6: Polling the Transaction Status

Once the Bank app has redirected the consumer back to your app, you can start polling the transaction status.

To start the PayByBankApp polling status:

1. Add the deeplinkURL to the configuration

2. Call the invokePBBA(configuration:) method:

func handleDeeplink() {
     guard let url = UserDefaults.standard.url(forKey: "deeplinkURL") else {
         return
     }

     configuration.pbbaConfiguration?.deeplinkURL = url

     judoKit.invokePBBA(with: configuration) { [weak self] (response, error) in
         if let response = response {
             // Handle response
         }

         if let error = error {
             // Handle error
         }
     }
 }

3. In the JPResponse object, you can inspect the orderDetails containing information about the transaction status.

Another option is to put a check in your viewDidAppear(animated:) method.

If a deeplinkURL is set up, add it to the configuration and call the invokePBBA(configuration:) method again. This will start the polling status.

Manually Checking the Transaction Status

There may be cases where the Bank app closes before the transaction flow completes. This would mean the deeplinkURL is not returned and the polling process to check the transaction status will not begin.

To manually check the transaction status:

1. Invoke a manual order status request:

   Use the JPApiService to invoke a manual order status request.

2. Get the orderId from the initial request:

judoKit.invokePBBA(with: configuration) { [weak self] (response, error) in 
    if let response = response { 
        let orderId = response.orderDetails?.orderId 
            // Persist the orderId for later use 
} 
}

3. Use the orderId to manually check the transaction status:

   Create an instance of JPApiService

You would do this in the same way as Initialising the Judopay SDK, see Step 1: Initialising the SDK.

4. Call the invokeOrderStatus method, with the orderId:

let apiService = JPApiService(authorization: authorization, isSandboxed: true)

    apiService.invokeOrderStatus(withOrderId: orderId) { (response, error) in
    // Handle response
}

The response will contain both the transaction status, and the order details of the transaction.

For a sample app, see Judopay's Judokit for iOS on Github.

Displaying iDEAL as a Payment Method for iOS

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.