Related: Enabling Apple Pay as a Payment Method
The Advanced Setup is intended for sellers with in‑house development resources who want deeper control over how Apple Pay behaves on their upsell pages. This includes:
Custom Apple Pay button styling or placement.
Custom error handling and logging.
Integration with client‑side frameworks such as React, Vue, or Angular.
Direct interaction with existing DOM rendering or state management.
Do not mix Standard and Advanced setups. If you implement a custom Apple Pay flow using the Advanced approach, you should remove the consolidated Standard script from those pages.
2.1 Prerequisites (Same as Standard Setup)
Before implementing any advanced code, you must still:
Request your Account Manager enable Allow Apple Pay (admin) in Vendor Settings → My Site.
Configure the Apple Pay ternary switch and register up to three domains in Vendor Settings → Order Form Control.
Publish the Apple Merchant ID association file on each domain at:
https://yourdomain.com/.well-known/apple-developer-merchantid-domain-association
2.2 When to Use Advanced Setup
Use the Advanced Setup only if you need to:
Render Apple Pay buttons conditionally in your own UI components.
Coordinate Apple Pay flows with:
Custom cart / offer selection logic, or
Client‑side validation and tracking events.
Integrate Apple Pay within:
Single‑page apps
React / Vue / Angular frontend frameworks
Server‑Side Rendered apps with client hydration
Customize messaging, retry logic, or redirection behavior on Apple Pay error.
Best practice: Implement and test your Advanced Setup first in Parameter Only mode using &apy on pay links. Once you are satisfied with behavior and metrics, move to Enabled.
2.3 High‑Level Advanced Flow
A typical advanced integration on an upsell page will follow this pattern:
Check if Apple Pay is available in the browser (e.g., using window.ApplePaySession).
Render a custom Apple Pay button (or component) only when supported.
On click, initialize an Apple Pay session with the offer details (line items, totals, merchant ID).
Handle Apple Pay callbacks:
Validation (merchant session)
Payment authorization
Cancellation & errors
On successful authorization, pass the Apple Pay token to ClickBank for fulfillment of the upsell.
On failure, route the customer back to the original order form or present a custom error message.
2.4 Advanced Apple Pay SDK Setup (Upsell Pages)
The following is a conceptual JavaScript example showing where you would plug in your own UI and framework logic. It is not a drop‑in script, but a reference for advanced implementations.
1️⃣ Load the Apple Pay SDK
<script>
window.addEventListener('CB-apple-pay-ready', () => {
window.CBApplePaySdk.init();
});
</script>
Important Rules:
CB-apple-pay-ready must fire before calling init().
CB-apple-pay-button class must be present on buttons to be initialized.
pmt=apple in the Upsell Page URL determines if this is an Apple payment flow.
2️⃣ Create Apple Pay Buttons
Buttons must include:
Class: CB-apple-pay-button
Required data attributes:
data-seller (Vendor ID)
data-item (SKU or item alias)
Example:
<button
class="CB-apple-pay-button"
data-seller="VENDOR_ID"
data-item="PRODUCT_SKU"
hidden>
</button>
Optional attributes:
data-coupon
data-funnel
The SDK scans for CB-apple-pay-button and initializes them automatically.
3️⃣ Conditional Display Logic
Best practice:
Render both:
Standard credit button (CB-default-button).
Apple Pay button (CB-apple-pay-button).
Hide both by default.
Based on pmt=apple, show the appropriate one.
Example logic:
const params = new URLSearchParams(window.location.search);
const isApple = params.get('pmt') === 'apple';
const buttonsToShow = isApple
? document.querySelectorAll('.CB-apple-pay-button')
: document.querySelectorAll('.CB-default-button');
buttonsToShow.forEach(btn => btn.removeAttribute('hidden'));
Error Handling Best Practices
You can listen for Apple Pay errors:
<script>
window.addEventListener('CB-apple-pay-error', (event) => {
const { type, item } = event.detail;
console.log('Error type:', type);
console.log('Item:', item);
// type can be:
// - payment
// - server
// - client
});
</script>
Recommended Handling
Payment error
Show user‑friendly message.
Offer fallback to credit card.
Server/client error
Redirect to the standard order form, or
Show an alternative payment method.
If multiple items are on page, event.detail.item tells you which item triggered the error.
2.5 Framework‑Specific Notes (React / SPA / Etc.)
Create a dedicated
<ApplePayButton />or similar component that:Checks
ApplePaySession.canMakePayments()on mount.Dispatches the
startApplePaySession()logic from a click handler.Uses framework‑native state for loading/error UI.
Avoid re‑creating sessions on every
render; tiethe session lifecycle to a deliberate user action (click).If you use client‑side routing, re‑check availability when a new upsell route is loaded.
2.6 Error Handling & Fallbacks
In an advanced integration, you have full control over how to respond to Apple Pay issues:
On validation errors, abort the session and show a human‑readable message (e.g., “Apple Pay is currently unavailable, please complete your purchase using a card.”).
On authorization failure, you may:
Return the user to the original order form.
Offer a different upsell path or payment method.
Log detailed information for debugging (without storing sensitive card data).
In all cases, maintain a working non‑Apple‑Pay checkout path so customers can still complete their purchase.