HomeMerchantsDevelopers

Apple Pay

Apple Pay is a payment wallet solution which allows users of Apple devices to make seamless credit/debit card backed payments through a simple and secure 'one-click' user interface. Support for Apple Pay can help improve both conversion and your customer experience, and is rapidly becoming a minimum requirement for proprietary merchant iOS applications that facilitate payment.

Before you start

Accepting Apple Pay payments through your N-Genius Online account relies on a number of pre-requisites, which you must be able to satisfy:

  • A valid and enrolled Apple Pay developer account (personal or organization)
  • An iOS app integrated with N-Genius Online

You can integrate Apple Pay with N-Genius by the following methods

  1. Using the N-Genius iOS SDK
  2. Direct Api Integration

Configuring Apple Pay

In order to begin accepting payments from Apple Pay users, you must first navigate to your N-Genius Online portal, log-in and browse to the Settings > Organisational hierarchy screen, and find the 'Payment channels' configuration option.

On the next screen, you will see a number of tabs indicating each type of payment channel, and how many are already configured.

Switch to the 'Wallets' tab to configure your Apple Pay integration.

Next, click on the 'certificate signing request' link to download the certificate signing request.

Upload this certificate signing request in Apple's developer portal to generate a new Payment processing certificate.

📘

Creating a payment processing certificate

You can navigate to Apple developer portal > Create new Payment processing certificate to create a new payment processing certificate.

On generating the payment processing certificate (PPC), upload the same on N-Genius portal by clicking the 'Upload signed certificate'.

On uploading the PPC, Apple pay is fully setup on your N-Genius Online account.

Integrating Apple app in-app

There are two ways to setup and configure Apple Pay in your iOS app

  1. NGenius SDK - Use the sdk to quickly integrate Apple Pay.
  2. Direct API - You can directly integrate using the Apple Pay and NGenius apis to get more control.

Apple Pay (Direct API)

1. Enable Apple Pay in-app capabilities

Add your Merchant ID generated in Apple's Developer portal to your project's .entitlements file under Merchant IDs

2. Implement PKPaymentAuthorizationViewControllerDelegate

import PassKit

func paymentAuthorizationViewController(_ controller: PKPaymentAuthorizationViewController,
                                            didSelect paymentMethod: PKPaymentMethod,
                                            handler completion: @escaping (PKPaymentRequestPaymentMethodUpdate) -> Void) {
            completion(PKPaymentRequestPaymentMethodUpdate(errors: nil, paymentSummaryItems: paymentSummaryItems))
    }
    
    func paymentAuthorizationViewController(_ controller: PKPaymentAuthorizationViewController,
                                            didSelect shippingMethod: PKShippingMethod,
                                            handler completion: @escaping (PKPaymentRequestShippingMethodUpdate) -> Void) {
            completion(PKPaymentRequestShippingMethodUpdate(paymentSummaryItems: paymentSummaryItems))
    }
    
    func paymentAuthorizationViewController(_ controller: PKPaymentAuthorizationViewController,
                                            didSelectShippingContact contact: PKContact,
                                            handler completion: @escaping (PKPaymentRequestShippingContactUpdate) -> Void) {
            completion(PKPaymentRequestShippingContactUpdate(errors: nil,
            paymentSummaryItems: paymentSummaryItems,
            shippingMethods: supportedShippingMethods))
    }
    
    func paymentAuthorizationViewController(_ controller: PKPaymentAuthorizationViewController,
                                            didAuthorizePayment payment: PKPayment,
                                            handler completion: @escaping (PKPaymentAuthorizationResult) -> Void) {
        self.onAuthorizeApplePayCallback(payment, {
            authorizationResult, paymentResponse in
            DispatchQueue.main.async {
                completion(authorizationResult)
                controller.dismiss(animated: false, completion: nil)
            }
        })
    }
    
    func paymentAuthorizationViewControllerDidFinish(_ controller: PKPaymentAuthorizationViewController) {
        controller.dismiss(animated: false, completion: nil)
    }

3. Create the order on Gateway

Please refer the order creation API for creating an order on the gateway. Two stage payments

4. Authorize the transaction on N-Genius

The order created should be authorised to obtain a paymentToken which is used to further post the Apple Pay encrypted object to N-Genius and process the payment.

The authorization link can be obtained from the order response object. A sample key path is shown below to fetch the payment link

{
  "_links": {
    "payment-authorization": {
      "href": "*https://payment-auth-link*"
    }
  }
}

A payment token can be requested By making a POST request to the above link.

  • HTTP Method: POST

  • Request Headers :

    "Accept": "application/vnd.ni-payment.v2+json",
    "Media-Type": "application/x-www-form-urlencoded",
    "Content-Type": "application/x-www-form-urlencoded"

5. Create the PassKitPaymentRequest Object

This PKPaymentRequest object is required by Apple Pay. You can derive the required fields from the gateway order created. Also care must be taken to populate the merchantIdentifier field with the correct MID field configured in both the Apple's dev portal and N-Genius portal.

The paymentSummaryItems is an array of PKPaymentSummaryItem which has information related to the line items of items purchased by the user. This is displayed to the user in the Apple Pay interface. The last Item in this array represents the total cost or the order amount which the customer will be charged.

import PassKit

paymentRequest = PKPaymentRequest()
paymentRequest?.merchantIdentifier = "Insert Mid created in Apple dev portal here"
paymentRequest?.countryCode = "COUNRY CODE"
paymentRequest?.currencyCode = "CURRENCY CODE"
paymentRequest?.requiredShippingContactFields = [.postalAddress, .emailAddress, .phoneNumber]
paymentRequest?.merchantCapabilities = [.capabilityDebit, .capabilityCredit, .capability3DS]
paymentRequest?.requiredBillingContactFields = [.postalAddress, .name]
paymentRequest?.paymentSummaryItems = [PKPaymentSummaryItem(label: "Line Item", amount: NSDecimalNumber(value: amount))]
paymentRequest?.paymentSummaryItems.append(PKPaymentSummaryItem(label: "Total", amount: NSDecimalNumber(value: paymentAmount)))

6. Initiate Apple Pay in app

Initialise the Apple Pay View controller and instantiate it with the PKPaymentRequest object created previously.

import PassKit

let pkPaymentAuthorizationVC = PKPaymentAuthorizationViewController(paymentRequest: applePayRequest)

self.present(pkPaymentAuthorizationVC, animated: false, completion: nil)

7. Post the Apple Pay encrypted object to N-Genius

When the user selects a card from the Apple Pay interface and authorizes a transaction, an encrypted object is received from Apple which needs to be posted to N-Genius in order to process the transaction and charge the customer.

  • HTTP verb : PUT

  • Body data: applePayPaymentResponse.token.paymentData

  • Request headers :

    "Authorization": "Bearer" + paymentToken,
    "Content-Type": "application/vnd.ni-payment.v2+json"

In the above request header, payment token is the token that is received during the authorization step

The body data is the paymentData response received from Apple Pay from the didAuthorizePayment method of PKPaymentAuthorizationViewControllerDelegate implemented in step 2

📘

Check if Apple Pay is setup

You can check if a user has setup Apple Pay on his device by making a call to PKPaymentAuthorizationViewController.canMakePayments(). This method will return a boolean value true if Apple pay is setup. You can use this method to conditionally render the Apple Pay button.

You can also check out Apple's guide to know which devices support Apple Pay

🚧

Troubleshooting Apple Pay Issues

While integrating with Apple Pay, if you encounter errors related to decryption or payment failures, this could be an issue of stale certificate being cached by Xcode. In such cases we recommend to create a new merchant identifier (MID) using a string value that has not been previously used in Apple's developer portal and re create the signed certificate against the new MID.

Apple Pay (N-Genius SDK)

Refer the SDK section for details on integrating Apple Pay using the N-Genius iOS SDK.