Broadleaf Microservices
  • v1.0.0-latest-prod

Apple Pay Checkout Flow

Apple Pay Implementation Details

The Apple Pay implementation consists of two main components. The first is interaction with the Apple libraries for session creation, validation, and generation of an Apple Pay Token. The second is using a payment provider, in this case Chase Orbital, to execute transactions against the Apple Pay Token we received.

There are couple Apple libraries that can be used on the frontend for Apple Pay on the web, Apple Pay JS API and Payment Request API. Either can be used to generate sessions and Apple Pay Tokens, but in our examples we will be using Apple Pay JS API. For the full documentation on Apple Pay JS API or the Payment Request API, you can visit Apple Pay on the Web documentation.

Apple Pay Session Creation

For the Apple Pay session creation, you should register a handler for the "click" event on the apple-pay-button. Within this handler method, build the ApplePayPaymentRequest for the ApplePaySession, register the callback events for the ApplePaySession - onvalidatemerchant, onpaymentmethodselected, and onpaymentauthorized at a minimum, and begin the session. When the user clicks the Apple Pay button, the payment sheet is loaded and the onvalidatemerchant callback is triggered. This callback function passes the event, including the session creation URL that should be validated, and calls the Chase Payment Module wallet endpoint, i.e POST /api/payment/chase-payment/wallet-session/applepay/create?createSessionUrl={event.validationURL}. On return from the POST API call, the session should call the completeMerchantValidation to complete the validation flow.

Example Implementation
    session.onvalidatemerchant = (event) => {
      // Pass the event's validationURL to create the session
      // `submitCreateApplePaySession` calls POST /api/payment/chase-payment/wallet-session/applepay/create?createSessionUrl={event.validationURL}
      submitCreateApplePaySession(event.validationURL)
        .then((merchantSession) => {
          // On success, passes the opaque Apple Pay session object to complete the validation
          session.completeMerchantValidation(merchantSession);
        })
        .catch(() => {
          session.completePayment(ApplePaySession.STATUS_FAILURE);
          setError(
            intl.formatMessage({
              defaultMessage:
                "An error occurred while processing your payment.",
            }),
          );
        });
    };

Apple Pay Token Creation

After the customer interacts with the payment sheet & authorizes the transaction, Apple will generate an Apple Pay Token. This token is returned on the frontend with the onpaymentauthorized callback event, and must be included on the CreatePaymentRequest within paymentMethodProperties so that PaymentTransactionServices can use that token during checkout for authorization.

Example Implementation
    session.onvalidatemerchant = (event) => {
      // Gets the Apple Pay Token from the event payment data
      const applePayToken = event.payment.token.paymentData;
      // Gets the billing address from the event
      const applePaymentBilling = event.payment.billingContact;

      const createPaymentRequest: CreatePaymentRequest = {
        name: 'Apple Pay',
        type: 'APPLE_PAY',
        gatewayType: 'CHASE_ORBITAL',
        amount: '122.85',
        shouldSavePaymentForFutureUse: false,
        isSingleUsePaymentMethod: true,
        paymentMethodProperties: {
          paymentInstrumentType: "APPLE_PAY_ENCRYPTED_BUNDLE",
          applePayToken: JSON.stringify(applePayToken),
          latitudeLongitude: latitudeLongitude,
        },
        billingAddress: getBillingAddressForApplePayment(applePaymentBilling),
      };

      // Call PaymentTransactionService with the `createPaymentRequest`
    }

For the general creation of a payment in the Chase Payment Module, see the documentation on preparing PTS payments.

Apple Pay in Chase Module

In the sections above, we discussed creating & validating the Apple Pay session. This requires the a POST request to the endpoint com.broadleafcommerce.vendor.chasepayment.web.endpoint.ChasePaymentWalletSessionEndpoint at the path /api/payment/chase-payment/wallet-session/applepay/create?createSessionUrl={event.validationURL}. The endpoint will be passed the URL returned from the Apple Session event, validate that it’s a valid Apple domain, and call it with the session request built on the configured properties. The properties that are responsible for building the session request can be found under broadleaf.chase-payment.apple-pay.*, see Apple Pay properties below.

In addition to handling creation of the session, we must also process the Apple Pay payment during checkout processing. This requires us calling the Chase Orbital gateway with the expected payload for an Apple Pay wallet, including the Apple Pay Token. In order for the Chase Payment Module to properly handle this request during checkout, the Payment created must contain the applePayToken and paymentInstrumentType of APPLE_PAY_ENCRYPTED_BUNDLE in paymentMethodProperties, the payment type must be APPLE_PAY, and the billingAddress must be provided if required for Merchant Selectable Responses (MSR). These properties will be used to generate a request to Chase Orbital so that the Apple Wallet payment will be processed.

Apple Pay Setup & Configuration

Apple Pay Properties

Note
 These properties are context-discriminated, and thus each property value can be overridden at the tenant/application level via broadleaf.chase-payment.apple-pay.{app or tenant ID}.{property name}
Property Description Default value

broadleaf.chase-payment.apple-pay.merchant-identity-certificate

The Apple Pay merchant identity certificate. The default provider implementation for this certificate expects the certificate provided here as a base64-encoded string. For example: M1ds…​7ewg==

none

broadleaf.chase-payment.apple-pay.merchant-identity-private-key

The Apple Pay merchant identity private key. The default provider implementation for this private key expects the key provided here as a base64-encoded string. For example: MR3t…​8jKt=

none

broadleaf.chase-payment.apple-pay.merchant-identifier

An identifier you register with Apple that uniquely identifies your business as a merchant able to accept payments

none

broadleaf.chase-payment.apple-pay.display-name

A string of 64 or fewer UTF-8 characters containing the canonical name for your store, suitable for display. Don’t localize the name.

none

broadleaf.chase-payment.apple-pay.initiative

A predefined value that identifies the e-commerce application making the request.

"web"

broadleaf.chase-payment.apple-pay.initiative-context

The values for initiative and initiativeContext depend on the kind of application you’re building:

For Apple Pay on the web, use “web” for the initiative parameter. For the initiativeContext parameter, provide your fully qualified domain name associated with your Apple Pay Merchant Identity Certificate. For example, "my-store-domain.com".

For Apple Messages for Business, use “messaging” for the initiative parameter. For the initiativeContext parameter, pass your payment gateway URL.

Please note, if initiative and initiativeContext are incorrect the validation of the Merchant session can fail.

none

broadleaf.chase-payment.apple-pay.valid-merchant-validation-domains

The list of valid domains for merchant validation in production and testing. This list of valid ApplePay domains are not application/tenant discriminated.

[ "apple-pay-gateway-cert.apple.com", "apple-pay-gateway.apple.com", "cn-apple-pay-gateway.apple.com", "cn-apple-pay-gateway-cert.apple.com" ]

Going to Production

Apple Pay Domain for Merchant Validation

By default, the property for Apple Pay validation domains contains both production and test environment domains. When preparing to go to production, you should define this property in your production env to only contain the production verification domains.

For example, set broadleaf.chase-payment.apple-pay.valid-merchant-validation-domains= [ "apple-pay-gateway.apple.com", "cn-apple-pay-gateway.apple.com" ].

See Apple Pay IP Addresses documentation for more details.

Apple Pay Certificate Creation

In addition, Apple Pay requires certificates to verify your integration. The two certificates needed are the Payment Processing Certificate and the Merchant Identity Certificate.

To create the Payment Processing Certificate, you should receive a Certificate Signing Request (CSR) file from your Chase representative. Upload that CSR in your Apple Developer Account under your merchant identifier, and Apple will generate a signed Payment Processing Certificate from it. You’ll need to manage and renew this certificate, so make sure you have a process to keep track of expiry dates & renewals.

To create the Merchant Identity Certificate, you should generate a CSR and upload it in your Apple Developer Account under your merchant identifier. Download the Merchant Identity Certificate from the Apple Developer Account, so that you can extract it into a .p12 file containing the certificate & private key. Using OpenSSL or similar, extract the .crt.pem and .key.pem files, take the base64 encoded value within those PEM files (ignoring the -----BEGIN header & -----END footer, and removing all the line breaks), and add those encoded strings to your broadleaf.chase-payment.apple-pay.merchant-identity-certificate and broadleaf.chase-payment.apple-pay.merchant-identity-private-key properties. Alternatively, if your certificate and key files are in the binary DER format, you can just base64 encode the entire files themselves and supply the output as the property values.

For more details on each of these steps, see the Apple Pay Merchant Integration Guide.