Recurly supports Apple Pay on the Web via Recurly.js v4 and Checkout across multiple gateways. Setup requires coordinating with Recurly Support to enable feature flags and generate Certificate Signing Requests (CSRs), which are then used to create certificates in the Apple Developer portal.

Available on all Recurly plans

1Definition 2Key details 3Checkout flow 4FAQs

Prerequisites

An Apple Developer account and a verified domain where your checkout page will reside.
Recurly.js v4 or Checkout.
A supported Apple Pay gateway: Adyen, Stripe, Braintree, Vantiv, Worldpay, Commerce Hub, Checkout.com, Chase Orbital, Nuvei, or CyberSource.
Zero Dollar Authorizations are supported with this payment method.

Limitations

Apple Pay on the Web is not available on Recurly Hosted Payment Pages (HPP). It is supported on Recurly Checkout.

Definition

Apple Pay on the Web lets customers make fast, secure payments on your website using Apple Pay, without entering card details manually. Recurly supports this through Recurly.js v4 and Checkout. Before starting integration, review Apple's getting started guide.

Key details

Use cases

Ecommerce checkout — Offer a fast, low-friction payment option for customers on your web pages using Apple Pay.

Subscription billing — Simplify recurring payment setup for customers with Apple Pay stored in their device wallet.

Multi-domain support — Contact Recurly Support about enabling the Merchant Registration API capability if you need Apple Pay across multiple domains.

Apple Pay in Chrome — Apple Pay is not natively supported in Recurly.js on Chrome, but you can load the latest version of Apple Pay JS in your environment to enable it. See the ApplePay Recurly.js documentation for details. Not supported in Recurly Checkout UI.

Token types

Understanding the token types used in Apple Pay helps you configure the correct behavior for subscriptions.

FPAN — Funding Primary Account Number

The actual credit card number physically printed on the card. Also referred to as PAN.

DPAN — Device Primary Account Number

A tokenized card number created when a consumer adds a card to a device wallet (e.g., iPhone Apple Wallet). DPANs are sent to gateways in place of the actual FPAN.

Tied to a specific device (e.g., a specific iPhone or iPad) and typically accompanied by a Cryptogram when the customer is in session.
DPANs are full card numbers with different digits from the FPAN, and can appear on receipts and other UI elements.
DPANs are invalidated when a consumer removes the card from their device. If they re-add the same card or add a new one, a new DPAN is created. Subscriptions using a DPAN can fail due to this consumer-driven behavior and are non-recoverable.

MPAN — Merchant-Level Token

A merchant-level token used for Apple Pay that is associated with the merchant rather than a specific device. MPANs are not transferable between merchants and are not suitable for M&A-related data migrations.

MPANs are not invalidated when a consumer removes their card from a device, making them subscription-friendly.
MPANs benefit from expiry date forwarding, but card number changes are not received via Account Updater. Apple may receive new FPAN details, but the MPAN in Recurly remains unchanged.
MPANs are full card numbers with different digits from the FPAN, and can appear on receipts and other UI elements.

Cryptogram

A one-time authentication value generated during an Apple Pay transaction. Cryptograms are not stored and must be sent on all customer-initiated transactions.

Best practices and compliance

DPAN to MPAN migration required Apple requires merchants to migrate from DPANs to MPANs for recurring subscriptions. This is a Visa requirement for recurring payments. Update your Recurly.js integration to request MPANs. After July 2025, merchants must request MPANs to avoid declines. DPANs are grandfathered in but are not guaranteed to work indefinitely.

Return customers — Use Recurly.js even when an existing account code or billing info is on file. Recurly.js collects device-related cryptogram data required for customer-initiated Apple Pay transactions. See re-authenticating existing billing information.
Always request MPANs — Set your integration to request Merchant-level tokens. Token type is exposed on the payment method as apple_pay (DPAN) or apple_pay_merchant_token (MPAN). Note: not all issuers support returning MPANs — this is not always an integration issue.

Using Apple Recurring Requests (MPAN)

To request MPANs for renewals, use Simple or Advanced Labeling in your Recurly.js integration.

Simple Labeling — Add the recurring flag to the Apple Pay constructor. See the Recurly.js Apple Pay documentation.
Advanced Labeling — Configure the RecurringPaymentRequest. See Apple's RecurringPaymentRequest documentation.

For full context, see Apple's documentation on specifying the recurring payment request.

Checkout flow

Step 1: Request keys and CSRs from Recurly Support

Contact Recurly Support to initiate the following:

Enable the Apple Pay Web Payments feature flag

Once enabled, a new Apple Pay checkbox will appear in your Gateway Settings. Check this box, then navigate to Configuration → Apple Pay to upload keys and certificates.

Obtain your Merchant ID and Payment Processing Keys

Recurly Support will provide the keys needed for Apple Pay integration.

Receive your Certificate Signing Requests (CSRs)

CSRs are required to create the Apple Pay Payment and Merchant Identity certificates. Each CSR is unique to your merchant account — allow several business days for generation. You must use the Recurly-provided CSRs to ensure the integration works correctly.

Step 2: Create certificates in the Apple Developer portal

Request an Apple Pay Certificate

In the Apple Developer portal, request an Apple Pay Certificate, select the correct Merchant ID, and upload the payment.csr file.

Request a Merchant Identity Certificate

Repeat the process, this time selecting Merchant Identity Certificate and uploading the merchant_id.csr file.

Certificate reference
Merchant Identity Certificate — authenticates your merchant sessions with Apple Pay servers.
Apple Pay Certificate (Payment Processing Certificate) — used to process transactions through Apple Pay.

Step 3: Upload certificates and finalize setup in Recurly

Open Apple Pay configuration

In Recurly, navigate to Configuration → Apple Pay.

Enter your verified domain

Enter your domain in the format www.DOMAIN.com. Do not use the domain listed under the cert_UID field — always use your actual store domain.

Enter your store name and billing update URL

Input your store name as it should appear to customers during checkout. Provide a URL where customers can update billing information (e.g., https://www.DOMAIN.com/login). If you use Hosted Pages Account Login, Recurly determines this URL automatically.

Upload keys and certificates

Map each file to the correct field:
Payment Processing Key → Payment Processing Private Key
Merchant ID Key → Merchant ID Private Key
Merchant Identity Certificate → Merchant ID Certificate
Apple Pay Certificate → Payment Processing Certificate

Braintree setup

Setting up Apple Pay with Braintree differs from other gateways and requires coordination between Recurly and Braintree.

Enable Apple Pay on Braintree

Follow Braintree's Apple Pay documentation, then update your Recurly.js v4 checkout page to incorporate Apple Pay with Braintree client authorization per Recurly's developer documentation.

Enable Apple Pay in Recurly

Contact Recurly to activate the Enable Apple Pay Web Payments feature flag, then select Enable Apple Pay on the Braintree Gateway Configuration page in Recurly.

Note When using Apple Pay with Braintree, no additional certificate configuration is needed under Configuration → Apple Pay in Recurly.

FAQs

What is Apple Pay on the Web?

Apple Pay on the Web lets customers make secure, fast payments on websites using Apple Pay. It integrates into your web pages via Recurly.js v4 for a streamlined checkout experience.

What are the prerequisites for integrating Apple Pay on the Web?

You need an Apple Developer account, a verified checkout domain, Recurly.js v4, and a supported Apple Pay gateway added to your Recurly site.

How do I enable Apple Pay on the Web?

Follow the checkout flow in this guide — it covers setting up your Apple Developer account, configuring settings in both Apple and Recurly, and working with Recurly Support to enable the feature flag and obtain CSR files.

What are Apple Pay Certificates and why are they needed?

The Merchant Identity Certificate authenticates your merchant sessions with Apple Pay servers. The Apple Pay (Payment Processing) Certificate processes transactions on your behalf. Both are required for the integration to function.

How do I set up Apple Pay with Braintree?

Braintree setup uses a different process. Follow Braintree's Apple Pay documentation to enable it on the Braintree side, then enable the feature flag in Recurly. No additional configuration under Configuration → Apple Pay is needed for Braintree.

Can I use Apple Pay on the Web with Recurly Hosted Payment Pages?

No — Apple Pay on the Web is not supported on Hosted Payment Pages. It works on your own web pages via Recurly.js v4 and on Recurly Checkout pages. See the Checkout documentation for more.

How do I contact Recurly Support?

Reach out via the Recurly Support page.

Where can I find detailed integration documentation?

See the Recurly.js Apple Pay documentation for full integration details.

What do I do when my CSRs are about to expire?

Contact Recurly Support to generate new CSRs. Once you have the new files, delete and re-upload all files yourself to control timing and minimize any downtime for customers using Apple Pay.