Apple Pay button

Apple Pay button
Add an Apple Pay button to your embedded payment form for one-tap checkout with biometric authentication on supported Apple devices

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.

Apple Pay button on payment form

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:

  1. Host the domain-verification file at:
    1
    
    HTTPS://[DOMAIN_NAME]/.well-known/apple-developer-merchantid-domain-association
    
    HTTPS access, correct MIME type text/plain, no authentication required. Host the file on each domain and subdomain where you intend to display the Apple Pay button.
  2. 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.

Before the Apple Pay button displays, ensure:

  • 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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "order_id": "123456",
  "amount": 1020,
  "currency": "USD",
  "order_description": "Premium package",
  "apple_pay_merchant_name": "Solidgate",
  "customer_email": "test@solidgate.com",
  "customer_first_name": "John",
  "customer_last_name": "Snow",
  "ip_address": "8.8.8.8",
  "geo_country": "USA",
  "platform": "WEB",
  "language": "en",
  "force3ds": true,
  "order_metadata": {
    "coupon_code": "NY2025",
    "partner_id": "123989"
  },
  "success_url": "https://merchant.example/success",
  "fail_url": "https://merchant.example/fail"
}

Billing flow

Pass Guide
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 Guide
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 Guide
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:

Billing 1.0 one-time product payment.
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.

This is not Billing 2.0 customer_id.

Example

4dad42f878

Description

Coupon ID in UUID v4 format for a product discount.

Active only when product_id is present.

Example

eb4c6e93-4c53-447a-b215-5d5786af9844


Billing 1.0 recurring subscription payment.
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.

This is not Billing 2.0 customer_id.

Example

4dad42f878

Description

Number of payment retries.

Example

1

Description

Coupon ID in UUID v4 format for a product discount.

Active only when product_id is present.

Example

eb4c6e93-4c53-447a-b215-5d5786af9844


Billing 2.0 recurring subscription payment.
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.

Use subscription as the value.

Example

subscription

Description

Billing 2.0 customer ID in cust_… format.

Do not send merchant customer_account_id with checkout.

Example

cust_01KMG2ABYPF6XS5DMJQ817C429

Description

Merchant-defined reference that identifies the subscription in your system.

Unique within the channel and immutable after creation. Letters digits underscore or hyphen only.

Example

order_ABC-123

Description

Product line item applied to the subscription.

Pass exactly one recurring product. Multiple recurring products are not supported.

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.

Provide either coupon_id or coupon_code not both.

Description

Coupon ID.

Cannot be used together with coupon_code.

Example

coup_abc123

Description

Coupon code entered by a customer.

Cannot be used together with 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.

At most 10 entries.

Example

1
2
3
4
{
  "campaign": "spring_2026",
  "channel": "ads"
}

Description

Trial period configuration.


Description

Trial pricing model.

Allowed values are free and paid.

Example

paid

Description

Trial duration.


Description

Trial duration in units.

Maximums are day ≤ 365 week ≤ 52 and month ≤ 12.

Example

7

Description

Trial duration unit.

Allowed values are minute hour day week month quarter and year.

Example

day

Description

Trial price in minor units.

Used for paid trials.

Example

199

Description

Delay before automatic settlement of the paid trial charge, in hours.

Example

48


Billing 2.0 one-time invoice checkout.
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.

Use invoice as the value.

Example

invoice

Description

Billing 2.0 customer ID in cust_… format.

Do not send merchant customer_account_id with checkout.

Example

cust_01KMG2ABYPF6XS5DMJQ817C429

Description

Merchant-defined reference that identifies the invoice in your system.

Unique within the channel and immutable after creation. Letters digits underscore or hyphen only.

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.

Provide either coupon_id or coupon_code not both.

Description

Coupon ID.

Cannot be used together with coupon_code.

Example

coup_abc123

Description

Coupon code entered by a customer.

Cannot be used together with coupon_id. Alphanumeric characters only.

Example

MAY2026


 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
  "order_id": "123456",
  "product_id": "47f95c95-3647-4c5b-ae6d-40fd8d3ac742",
  "customer_account_id": "4dad42f808",
  "currency": "USD",
  "order_description": "Premium package",
  "apple_pay_merchant_name": "Solidgate",
  "customer_email": "test@solidgate.com",
  "ip_address": "8.8.8.8",
  "geo_country": "USA",
  "platform": "WEB",
  "language": "en",
  "success_url": "https://merchant.example/success",
  "fail_url": "https://merchant.example/fail"
}
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
{
  "order_id": "123456",
  "product_id": "faf3b86a-1fe6-4ae5-84d4-ab0651d75db2",
  "customer_account_id": "4dad42f808",
  "currency": "USD",
  "order_description": "Premium package",
  "apple_pay_merchant_name": "Solidgate",
  "customer_email": "test@solidgate.com",
  "ip_address": "8.8.8.8",
  "geo_country": "USA",
  "platform": "WEB",
  "language": "en",
  "retry_attempt": 1,
  "success_url": "https://merchant.example/success",
  "fail_url": "https://merchant.example/fail"
}
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
  "order_id": "123456",
  "order_description": "Premium package",
  "checkout": {
    "mode": "subscription",
    "customer_id": "cust_01KMG2ABYPF6XS5DMJQ817C429",
    "merchant_reference": "order_ABC-123",
    "line_items": [
      {
        "product_price_id": "fa43b415-5522-4373-b026-a365562f9649",
        "quantity": 1
      }
    ]
  },
  "apple_pay_merchant_name": "Solidgate",
  "customer_email": "test@solidgate.com",
  "ip_address": "8.8.8.8",
  "geo_country": "USA",
  "platform": "WEB",
  "language": "en",
  "order_metadata": {
    "partner_id": "123989"
  },
  "success_url": "https://merchant.example/success",
  "fail_url": "https://merchant.example/fail"
}
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
  "order_id": "123456",
  "order_description": "Premium package",
  "checkout": {
    "mode": "invoice",
    "customer_id": "cust_01KMG2ABYPF6XS5DMJQ817C429",
    "merchant_reference": "order_ABC-123",
    "line_items": [
      {
        "product_price_id": "fa43b415-5522-4373-b026-a365562f9649",
        "quantity": 2,
        "description": "Premium plan"
      }
    ]
  },
  "apple_pay_merchant_name": "Solidgate",
  "customer_email": "test@solidgate.com",
  "ip_address": "8.8.8.8",
  "geo_country": "USA",
  "platform": "WEB",
  "language": "en",
  "order_metadata": {
    "partner_id": "123989"
  },
  "success_url": "https://merchant.example/success",
  "fail_url": "https://merchant.example/fail"
}

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.

Apple Pay is not supported in Guide
Follow implementation best practices for the payment form including error handling, mobile optimization, and production validation steps.
certain
regions, including India.

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

  1. Add a new integrationType parameter for the applePayButtonParams object.
    By default, the integrationType is set to css , representing the previous, well-tested, and stable integration method.
  2. Update the integrationType by setting it to js .
  3. 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.
1
2
3
4
5
6
form.init({
  applePayButtonParams: {
    integrationType: 'js'
  },
  // ...other configurations
});

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-src for Apple Pay button images
  • script-src for Apple Pay JavaScript SDK
  • frame-src for 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 Guide
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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
import React, { FC } from 'react'
import ReactDOM from 'react-dom';
import Payment, { InitConfig } from "@solidgate/react-sdk"

export const MyPayment: FC<{
  merchantData: InitConfig['merchantData']
}> = (props) => {
  const appleContainerRef = useRef(null)

  return (
    <div>
      <div ref={appleContainerRef}></div>
      <Payment
        merchantData={props.merchantData}
        applePayContainerRef={appleContainerRef}
      />
    </div>
  )
}
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
<div id="yourCustomContainerId"></div>
<script>
PaymentFormSdk.init({
  ...restData,
  applePayButtonParams: {
    buttonType: 'buy',
    buttonColor: 'black',
    containerId: 'yourCustomContainerId'
  }
});
</script>
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
<template>
  <Payment
      :merchant-data="merchantData"
      :apple-pay-container-ref="appleButton"
  />
  <div ref="appleButton" />
</template>

<script lang="ts" setup>
import { defineAsyncComponent, ref } from 'vue'
import { InitConfig } from '@solidgate/vue-sdk'
const Payment = defineAsyncComponent(() => import('@solidgate/vue-sdk'))

const appleButton = ref<HTMLDivElement>()

const merchantData: InitConfig['merchantData'] = {
  merchant: '<<--YOUR MERCHANT ID-->>',
  signature: '<<--YOUR SIGNATURE OF THE REQUEST-->>',
  paymentIntent: '<<--YOUR PAYMENT INTENT-->>'
}
</script>
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
import {Component} from '@angular/core';

import {FormType, InitConfig} from "@solidgate/angular-sdk";

@Component({
  selector: 'app-root',
  template: `
    <ngx-solid-payment
      [merchantData]="merchantData"
      [applePayContainer]="applePay"
    ></ngx-solid-payment>
    <div class="apple-pay" #applePay></div>
  `
})
export class AppComponent {
  merchantData: InitConfig['merchantData'] = {
    merchant: '<<--YOUR MERCHANT ID-->>',
    signature: '<<--YOUR SIGNATURE OF THE REQUEST-->>',
    paymentIntent: '<<--YOUR PAYMENT INTENT-->>'
  }
}
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
<!-- MyPayment.svelte -->
<script lang="ts">
  import type { Action } from 'svelte/action'
  import { SdkLoader, type ClientSdk, type InitConfig } from '@solidgate/client-sdk-loader'

  let { merchantData }: { merchantData: InitConfig['merchantData'] } = $props()

  const containerId = $props.id()
  const applePayContainerId = `${containerId}-apple-pay`

  const payment: Action = (node) => {
    node.id = containerId

    let sdk: ClientSdk | null = null
    let cancelled = false

    void (async () => {
      sdk = await SdkLoader.load()
      if (!sdk || cancelled) return

      sdk.init({
        merchantData,
        iframeParams: { containerId, width: '100%' },
        applePayButtonParams: { containerId: applePayContainerId }
      })
    })()

    return {
      destroy () {
        cancelled = true
        sdk?.destroy()
      }
    }
  }
</script>

<div id={applePayContainerId}></div>
<div use:payment></div>

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.

Container with 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.

1
2
3
4
5
6
7
8
9
PaymentFormSdk.init({
  ...restData,
  applePayButtonParams: {
    enabled: false,
    containerId: 'yourCustomContainerId',
    color: 'white-outline',
    type: 'check-out'
  }
})

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 .


Looking for help? Contact us
Stay informed with Changelog