Judopay Documentation

Apple Pay™ for Mobile

Note

Apple Pay™ for Mobile only.

Apple Pay™ provides an easy and secure way to pay for physical goods and services such as groceries, clothing, tickets, and reservations in your iOS apps or on your website.

Using Touch ID, users can quickly and securely provide all their payment and shipping information to check out with a single touch.

 

Note

It is important to understand the difference between Apple Pay™ and an In-App Purchase.

Use Apple Pay™ to sell physical goods and services.

Use an In-App Purchase to sell virtual goods such as premium content for your app, and subscriptions for digital content.

For consumers, the Apple Pay™ experience starts with:

  1. Registering their payment and shipping information into the Wallet app on their Apple devices.

  2. Once registered, consumers can pay simply and securely using Touch ID to authenticate a transaction.

  3. Each transaction processed through Apple Pay™ is assigned a one-time payment number and a dynamic security code.

    1. This information is encrypted and used in place of credit or debit card details.

Effective implementations of Apple Pay™ can radically improve your payment process by allowing for a smoother ‘guest checkout’, while still capturing all the relevant information needed to fulfil a purchase, for example shipping information.

See the following integration guides to integrate Apple Pay™ for:

Apple Pay™ Set Up

Caution

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

  • OS 8.1 or newer

  • Xcode 6.1 or newer

Create a Merchant ID

Tip

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 a Merchant ID:

Apple Certificate

Step

Description

One.png

Access your Apple Developer Account.

Navigate to Certificates, Identifiers & Profiles.

Two.png

From the side menu, click Merchant IDs.

Three.png

In the iOS Merchant ID Settings screen, click the add button.

Four.png

Set your Merchant ID.

The identifier you enter should be a reverse DNS style identifier prefixed with the word.

Five.png

Click Done.

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 Pay Certificate

Step

Description

One.png

From the side menu, select either:

  • Certificates > All

  • Merchant ID

Two.png

The screen appears describing how to manually create your Certificate Signing Request (CSR).

As you’ve already obtained your CSR from Judopay, click Continue.

Three.png

You will be prompted to state if you are processing transactions outside the United States.

Select No.

Four.png

Click Continue.

Five.png

Click Choose File to upload the CSR file provided by Judopay.

Six.png

Click Generate.

Seven.png

The confirmation screen appears.

Your certificate is ready to download.

Click Download.

Eight.png

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.

Note

Apple Certificates expire just over two years after generation. For example a certificate generated on 13th May 2020 will expire on the 11th June 2021.

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:

Apple Pay Entitlement

Step

Description

One.png

Select your build Target.

Two.png

Select Capabilities.

Three.png

Set the entitlement to Enabled.

Four.png

Add the Merchant ID created earlier to the app.

You may need to refresh the list.

Five.png

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 theMobile SDK to start making payments.

Apple Pay™ Button

Apple Pay™ allows the consumer to:

  • Bypass the standard checkout flow

  • Complete their payment with speed

Apple Pay Button

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.

iOS

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

Caution

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

Note

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.

Note

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

  • Set the Apple Pay™ configuration:

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

Displaying Apple Pay™ as a Payment Method

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

Tip

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

Example:

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

Parameter

Description

ContactFieldName

Consumer's name.

ContactFieldEmail

Consumer's valid email address.

ContactFieldPhone

Consumer's valid phone number.

ContactFieldPostalAddress

Consumer's postal address.

ContactFieldAll

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

Parameter

Description

ShippingTypeShipping

Shipping.

The default value.

ShippingTypeDelivery

Delivery.

ShippingTypeStorePickup

Store Pickup.

ShippingTypeServicePickup

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:

1. Set the returnedContactInfo: applePayConfig.returnedContactInfo = ReturnedInfoBillingContacts;

Parameter

Description

ReturnedInfoBillingContacts

Billing details returned.

The default value.

ReturnedInfoShippingContacts

Shipping details returned.

ReturnedInfoAll

Billing and Shipping details returned.

React Native

Configuring Apple Pay™ for React Native

Prerequisite

  • You have set up your Apple Pay™ Developer Account to get your Merchant IDs.

    For more details, see Create a Merchant ID.

To make an Apple Pay™ transaction, or to add Apple Pay™ as a payment method in the Payment Method Selection screen, create an applePayConfiguration instance:

 

Below is an example of an applePayConfiguration property:

const applePayConfiguration: JudoApplePayConfiguration = {
merchantId: 'my-merchant-id',
countryCode: 'GB',
paymentSummaryItems: [item],
requiredBillingContactFields: JudoContactField.Name | JudoContactField.Email,
requiredShippingContactFields: JudoContactField.All,
shippingMethods: [delivery],
shippingType: JudoShippingType.Delivery,
returnedInfo: JudoReturnedInfo.All,
}

Parameter

Description

merchantId

String

Required

Your merchant ID that identifies you to Apple Pay™ as being able to accept payments.

countryCode

String

Required

An ISO 3166-1 Alpha-2 country code.

paymentSummaryItems

JudoPaymentSummaryItem[]

Required

A list of payment summary items that represent the item names | prices | types.

requiredBillingContactFields

JudoContactField

Optional

Select between one or more billing contact fields.

For example:

  • Email

  • Phone

  • Name

requiredShippingContactFields

JudoContactField

Optional

Select between one or more shipping contact fields.

For example:

  • Email

  • Phone

  • Name

shippingMethods

JudoShippingMethod[]

Optional

Describe some of the shipping methods that you provide.

Note: Although this parameter is optional, if you set shipping contact fields as required, you must also provide the shipping type and shipping methods.

shippingType

JudoShippingType

Optional

Select a shipping type:

  • Delivery

  • Shipping

  • Store Pickup

  • Service Pickup

Note: Although this parameter is optional, if you set shipping contact fields as required, you must also provide the shipping type and shipping methods.

returnedInfo

JudoReturnedInfo

Optional

Select to receive some of the billing and/or shipping details as a response property.

Displaying Apple Pay™ as a Payment Method

To display Apple Pay™ in the Payments Widget:

1. Add the applePayConfiguration property to the JudoConfiguration instance:

const configuration: JudoConfiguration = {
 judoId: 'my-judo-id',
    amount: amount,
    reference: reference,
    applePayConfiguration: applePayConfiguration,
}

2. Call the ApplePay method and handle the response:

import { ..., JudoTransactionMode, ... } from 'judo-react-native'
judo.invokeApplePay(JudoTransactionMode.Payment, configuration)
.then((response) => {/* Handle response */})
.catch((error) => {/* Handle error */})

Note

Use the JudoTransactionMode property instead of JudoTransactionType to limit the options to Payment or PreAuth.

This leaves JudoTransactionType to deal with Save Card | Register Card.

Making an Apple Pay™ Transaction

An example of an Apple Pay™ transaction:

import { ..., JudoTransactionMode, ... } from 'judo-react-native'

// Describing the purchased items
const itemOne: JudoPaymentSummaryItem = {
    label: 'Apple iPhone XR',
    amount: '699.95',
}
const itemTwo: JudoPaymentSummaryItem = {
    label: 'Apple Leather Case',
    amount: '55.50',
}
const total: JudoPaymentSummaryItem = {
    label: 'Tim Apple',
    amount: '755.45',
}

// Describe the shipping method
const delivery: JudoShippingMethod = {
    identifier: 'delivery-id',
    label: 'Delivery',
    detail: 'Deliver to your home address',
    amount: '15.0',
}

Caution

The last item in the JudoPaymentSummaryItem list must always represent the total amount of the previous items.