Apple Pay

Apple Pay is a seamless and secure payment method that enhances the checkout experience for customers using Apple devices. This guide will walk you through the process of integrating Apple Pay with .

Eligibility

Apple Pay is only available for merchants onboarded to Flex Billing with Paysafe. If you have questions about your merchant's processor and billing owner, reach out to .

Prerequisites

Before you begin, ensure you have the following:

An Apple Developer account
Access to your API keys
An Apple Pay-enabled device for testing

Implement Apple Pay

Verify your domain for Apple Pay

To use Apple Pay, you will need to register and verify every domain and subdomain where the Apple Pay button will appear. For example, if you display the Apple Pay button on https://pay.example.com/ (opens in a new tab) and https://example.com/ (opens in a new tab), you need to verify both domains.

Sandbox environment

Domain verification is not required, but you must still adhere to domain requirements.

Production environment

To obtain your domain verification files for Apple Pay, provide the following details to :

Number of domains: Specify how many domains will host the Apple Pay button. If each merchant uses a different domain or subdomain, include that information.
Number of merchants: Indicate how many merchants will be enabled for Apple Pay.
Checkout method: Specify whether you will use your own checkout page (using Payments.jsJS) or hosted options such as Payment Links or Checkout Sessions.

Initialize Payments.js

To accept Apple Pay payments through using your own checkout page, you need to include Payments.jsJS on your page. Add the following HTML snippet to your web page, preferably within the <head> tag.

<script src="{{TILLED_JS_URL}}"></script>

After including Payments.jsJS, you need to set it up by providing your publishable API key and the account_id of the merchant account you are performing the action on behalf of:

const {{TILLED_JS_TEXT_LOWERCASE}} = new {{TILLED_JS_TEXT}}('pk_…', 'acct_…');

Use new Payments(publishableKey, paymentsAccount, options?) to create an instance of the Payments object, which provides access to the rest of the Payments.jsJS SDK. Your publishable API key is required for this function. Replace the sample API key with your actual API key.

Create Payment Request

In this example, we'll use a <div id="native-payment-element"> container to inject the PaymentRequest button (Apple Pay button) if paymentRequest.canMakePayment(): Promise<boolean> returns true.

PaymentRequest instances emit several types of events. We will use payments.paymentRequest to create a PaymentRequest object.

In Safari, payments.paymentRequest uses Apple Pay.

const paymentRequest = {{TILLED_JS_TEXT_LOWERCASE}}.paymentRequest({
	total: {
		label: "{{COMPANY_NAME}} tee",
		amount: paymentIntent.amount,
	},
	style: {
		type: "donate",
		theme: "black",
	},
	requestPayerName: true,
	requestPayerEmail: true,});

When creating a PaymentRequest for Apple Pay, collecting the customer’s name is highly recommended. This also results in the collection of the billing address, which can be used for address verification. Set requestPayerName to true to collect the customer name.

For a full list of PaymentRequest options properties, refer to the documentation here (opens in a new tab).

Note: Neither Apple Pay nor PaymentRequest are unique payment method types. Payment methods created by a PaymentRequest will have a type of card.

Display Apple Pay button

To ensure that only customers with an active Apple Pay Wallet see the option to pay with Apple Pay, use the paymentRequest.canMakePayment() method. This method returns a Promise that resolves to true if an enabled wallet is available and ready to pay. If no wallet is available, it resolves to false.

The following example demonstrates how to inject the Apple Pay button into a <div id="native-payment-element"> container if paymentRequest.canMakePayment() resolves to true:

var prButton = form.createField('paymentRequestButton', {
  paymentRequest: paymentRequest,
});

paymentRequest.canMakePayment().then((result) => {
  if (result) {
    // Inject paymentRequestButton Form Field to the DOM
    prButton.inject('#native-payment-element');
  }
});

Create a payment method

Payments.jsJS automatically creates a payment method once the customer completes the payment process in their browser. You can access the created payment method by listening for the paymentmethod event using paymentRequest.on('paymentmethod', handler): void.

Payment methods created through Apple Pay will have a type of card and a validity period of 5 minutes.

Create and confirm the payment intent

Before displaying your checkout form and confirming the payment, your backend server needs to Create a Payment IntentAPI with the payment amount. Pass the client_secret of the intent to your frontend.

paymentRequest.on('paymentmethod', (ev) => {
  let paymentMethod = ev.paymentMethod;
  {{TILLED_JS_TEXT_LOWERCASE}}
    .confirmPayment(paymentIntentClientSecret, {
      payment_method: paymentMethod.id,
    })
    .then(
      (paymentIntent) => {
        // The payment intent confirmation occurred, but the
        // actual charge may still have failed. Check
        if (
          paymentIntent.status === 'succeeded' ||
          paymentIntent.status === 'processing'
        ) {
          ev.complete('success');
          alert('Successful payment');
        } else {
          ev.complete('fail');
          const errMsg = paymentIntent.last_payment_error?.message;
          alert('Payment failed: ' + errMsg);
        }
      },
      (err) => {
        ev.complete('fail');
      },
    );
});

Test Apple Pay Integration

Apple allows developers to test Apple Pay either before or after implementation by using a sandbox tester account (opens in a new tab).

Validate domain requirements

Confirm that your domain is secured with HTTPS (TLS 1.2 or later).
Verify that you have a valid SSL Certificate.
Make sure your domain has been validated utilizing API and is actively hosting the Domain Verification file at the path: /.well-known/apple-developer-merchantid-domain-association.

Enroll in Apple Developer Program

If you haven't already, enroll in the Apple Developer Program (opens in a new tab) to access necessary developer resources.

Create sandbox tester account

To create a sandbox tester account, refer to Apple's instructions (opens in a new tab).

Test Apple Pay checkout flow

Sign into your sandbox tester account on the device used to test your integration.
Add a test card number to your Apple Pay Wallet from the selection of test cards provided by Apple.
Checkout using the Apple Pay test card.

Level 2/3 On-Device Tipping