This guide outlines the steps to enable Apple Pay on your Payment Form, following Apple’s development requirements. Once set up, the payment form features the Apple Pay button, enhancing your payment options.

Payment Form complies with Apple's development requirements Reference for Apple Pay on the Web. Apple Pay is available in supported regions Reference and on specific platforms Reference in Safari, and in non-Safari browsers.
Before displaying the button, complete the Apple Pay integration setup including certificates and domain verification with Apple.
Display button
To integrate the Apple Pay button and start accepting Apple Pay payments through the Payment Form:
- Host the domain-verification file at:
HTTPS access, correct MIME type
1HTTPS://[DOMAIN_NAME]/.well-known/apple-developer-merchantid-domain-associationtext/plain, no authentication required. Host the file on each domain and subdomain where you intend to display the Apple Pay button. - Complete the domain verification by adding the domain in the Developers section of Solidgate Hub . Each domain and subdomain must be verified separately.
Before adding certificates to your channels, confirm you want Apple Pay button integration rather than other payment methods.
- Domain-verification file is accessible on each domain and subdomain that hosts the checkout
- Each domain and subdomain is verified in Solidgate Hub
- Certificate configuration is confirmed
If you request to create a payment form with Apple Pay without verifying the domain, the button is not displayed, and the appropriate warning is sent.
Once the domain is verified and certificates are configured, configure the paymentIntent object with the fields below to display the Apple Pay button on the Payment Form. You can additionally hide the button if necessary.
|
|
Billing flow
Pass
Pass Billing-specific fields in paymentIntent for catalog products, subscriptions, and invoices.
Billing-specific
fields in paymentIntent for catalog products, subscriptions, and invoices. Match the scenario to your Billing version.
The paymentIntent object lists fields the Apple Pay button needs. Combine both on the same intent. Subscription 2.0 and Invoice omit top-level amount, currency, and product_id.
After the form is initialized with a checkout object, replace line items, discounts, or trial terms in the
Replace checkout line items, discounts, and trial terms on an initialized Billing checkout form using the form.updateCheckout method.
checkout update
flow. Totals still come from checkout.line_items. Match the wallet payment sheet total with the
The invoicePreview event reports the calculated invoice for a Billing checkout intent at form initialization and after a billing address change.
invoicePreview
event.
Select the Billing flow:
Provide
product_id and merchant customer_account_id.
Description
Identifier of the predefined product in UUID v4 format.
Example
faf3b86a-1fe6-4ae5-84d4-ab0651d75db2
Description
Merchant-defined customer ID for Billing 1.0.
customer_id.Example
4dad42f878
Description
Coupon ID in UUID v4 format for a product discount.
product_id is present.Example
eb4c6e93-4c53-447a-b215-5d5786af9844
Provide
product_id and merchant customer_account_id.
Description
Identifier of the predefined product in UUID v4 format.
Example
faf3b86a-1fe6-4ae5-84d4-ab0651d75db2
Description
Merchant-defined customer ID for Billing 1.0.
customer_id.Example
4dad42f878
Description
Number of payment retries.
Example
1
Description
Coupon ID in UUID v4 format for a product discount.
product_id is present.Example
eb4c6e93-4c53-447a-b215-5d5786af9844
Provide a
checkout object with mode as
subscription
and Billing customer_id. Pass exactly one recurring product in line_items.
Description
Recurring subscription payment parameters with one recurring line item, discounts, customer, and subscription data.
Description
Checkout flow type for a recurring subscription payment.
subscription as the value.Example
subscription
Description
Billing 2.0 customer ID in cust_… format.
customer_account_id with checkout.Example
cust_01KMG2ABYPF6XS5DMJQ817C429
Description
Merchant-defined reference that identifies the subscription in your system.
Example
order_ABC-123
Description
Product line item applied to the subscription.
Description
Product price ID charged on this line.
Example
fa43b415-5522-4373-b026-a365562f9649
Description
Number of units of product_price_id on this line.
Example
1
Description
Coupon applied to the subscription.
coupon_id or coupon_code not both.Description
Coupon ID.
coupon_code.Example
coup_abc123
Description
Coupon code entered by a customer.
coupon_id. Alphanumeric characters only.Example
MAY2026
Description
Subscription configuration.
Description
Subscription description.
Example
Premium plan annual
Description
Custom string key/value pairs attached to the subscription.
Example
|
|
Description
Trial period configuration.
Description
Trial pricing model.
free and paid.Example
paid
Description
Trial duration.
Description
Trial duration in units.
day ≤ 365 week ≤ 52 and month ≤ 12.Example
7
Description
Trial duration unit.
minute hour day week month quarter and year.Example
day
Description
Trial price in minor units.
Example
199
Description
Delay before automatic settlement of the paid trial charge, in hours.
Example
48
Provide a
checkout object with mode as
invoice
and Billing customer_id.
Description
One-time invoice payment parameters with line items discounts and customer details.
Description
Checkout flow type for a one-time invoice payment.
invoice as the value.Example
invoice
Description
Billing 2.0 customer ID in cust_… format.
customer_account_id with checkout.Example
cust_01KMG2ABYPF6XS5DMJQ817C429
Description
Merchant-defined reference that identifies the invoice in your system.
Example
order_ABC-123
Description
Product line item applied to the invoice.
Description
Product price ID charged on this line.
Example
fa43b415-5522-4373-b026-a365562f9649
Description
Number of units of product_price_id on this line.
Example
2
Description
Per-line description shown on the invoice.
Example
Premium plan
Description
Coupon applied to the cart.
coupon_id or coupon_code not both.Description
Coupon ID.
coupon_code.Example
coup_abc123
Description
Coupon code entered by a customer.
coupon_id. Alphanumeric characters only.Example
MAY2026
|
|
|
|
|
|
|
|
Subscribe to the mounted event to check when the Apple Pay button is set up and displayed. When the event is emitted for the applebtn entity, this means the Apple Pay button is fully displayed.
You can test the Apple Pay payments when setting up the integration.
Non-Safari browsers
Customers can complete purchases with Apple Pay on devices running macOS, Windows, and other operating systems using third-party browsers. During checkout, they can see the Apple Pay option and can finalize the transaction by scanning a QR code.
When Apple’s JavaScript object detects a non-Safari browser, it generates a QR code for transaction processing. The QR code can then be scanned with an iPhone running iOS 18 or later to complete the purchase through the familiar Apple Pay process. This approach is necessary, as many browsers do not natively support Apple Pay. Merchants must update their integration to enable Apple Pay in browsers other than Safari.
To enable Apple Pay in non-Safari browsers
- Add a new
integrationTypeparameter for theapplePayButtonParamsobject.
By default, theintegrationTypeis set to css , representing the previous, well-tested, and stable integration method. - Update the
integrationTypeby setting it to js . - Check your website appearance after the changes.
The new integration type uses the WebComponents approach, which could result in visual differences between old and new versions, depending on your website styling.
|
|
When using the JavaScript integration type integrationType: ‘js’, update your Content Security Policy (CSP) to allow Apple Pay resources. Add https://applepay.cdn-apple.com/ to your CSP directives:
img-srcfor Apple Pay button imagesscript-srcfor Apple Pay JavaScript SDKframe-srcfor Apple Pay payment sheet iframes
For the complete list of required CSP directives and their values, refer to the Apple Pay JS SDK Reference.
Customization
In addition to displaying the button on the payment form, you can also control the button position, color, and type. Use the applePayButtonParams object for changes as you would for all other
Customize payment form appearance with CSS overrides, theme configuration, font selection, and layout adjustments to match your brand.
customizations
in the Solidgate Payment Form.
To maintain a consistent and recognizable customer experience, Apple Pay supports only the customization of predefined styles. It is required to follow official design guidelines and the use of custom CSS or images is not allowed. For more information, check the Apple Pay button design guidelines Reference .
Button position
To set the Apple Pay button position, create, and specify a div, pass its id attribute value to the containerId parameter in the applePayButtonParams object.
|
|
|
|
|
|
|
|
|
|
In this example, the div with the ID yourCustomContainerId is created and the containerId parameter in the applePayButtonParams object is set to the value yourCustomContainerId.
Without a specified containerId, the button appears by default above all fields of the Payment Form. If a non-existing container is specified, an error message appears in the console.
id =‘specified-container’
does not exist.
Button styling
To change the button style, two parameters can be changed in the applePayButtonParams object:
- black - use on white or light-color backgrounds that provide sufficient contrast. Avoid using on black or dark backgrounds.
- white-outline - use on white or light-color backgrounds that do not provide sufficient contrast. Do not place on dark or saturated backgrounds.
- white - use on dark-color backgrounds that provide sufficient contrast.
Apple provides several types of buttons so that you can choose the button type that fits best with the terminology and flow of your purchase or payment experience. You can find more information in the Apple Pay Guidelines.
The following button types are not supported by Solidgate:
- donate
- support
- rent
- contribute
- tip
Button hiding
To hide the button from the customer, pass
false
to the enabled parameter. You do not need to specify
true
to display the button on the form as it is the default value. When you pass the
false
value, it means that the form with the passed parameters of containerId, color, and type is collected but not displayed on the Payment Form.
|
|
Apple payment sheet
Solidgate Payment Form gives you access to customize merchant name label on the Apple Payment Sheet Reference .
To display your merchant name, pass the apple_pay_merchant_name parameter in the paymentIntent object. If you omit it, the Apple Payment Sheet shows Apple’s default name
Seller
.