Apple Pay button : Help Center

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: Domain-verification file location
```
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.
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.

order_id string 255 Required

Description

Order ID, which must be unique, is specified in the merchant system.

Example

123456

order_description string 255 Required

Description

Order description in your system and for bank processing.

Highly recommended to keep the description brief to improve the clarity of payment processing, ideally not exceeding 100 characters. It is used in the email receipt sent to the customer.

Example

Premium package

currency string 3 Required

Description

Currency in three-letter code per the ISO-4217 Wiki standard.

Should not be provided for Subscription 2.0 and Invoice in Billing flow.

Example

USD

amount integer >=0 Required

Description

Order amount in minor units. For example, 1020 means 10 USD and 20 cents. Can be 0 for zero-amount authorization.

Example

1020

apple_pay_merchant_name string 64

Description

Merchant name, which can be displayed to the customers on the Apple Payment Sheet when paying via Apple Pay.

Recommended to pass this parameter. If not provided, the Apple Payment Sheet displays Apple’s default name Seller . There is no channel-level merchant name fallback.

Example

Solidgate

apple_pay_merchant_domain string

Description

Domain where you have uploaded the domain-verification file. Automatically configured from the internal database. Do not pass it in the request.

Example

solidgate.com

customer_email string 100

Description

Customer email.

If not provided, it is collected on the payment form.

Example

test@solidgate.com

customer_first_name string 100

Description

Customer’s first name.

Example

John

customer_last_name string 100

Description

Customer’s last name.

Example

Snow

ip_address string 50

Description

Public IP address of the customer. Both IPv4 and IPv6 are supported.

Private IPs (10.0.0.0-10.255.255.255, 172.16.0.0-172.31.255.255, 192.168.0.0-192.168.255.255) result in an ‘Invalid IP’ error.

Example

8.8.8.8

geo_country string 3

Description

Customer country subject to ISO-3166 Wiki alpha-3.

If not provided, it is automatically inferred. Apple Pay is unavailable in restricted regions.

Example

USA

platform string 3

Description

Customer platform at the moment of payment.

WEB - desktop
MOB - mobile version
APP - application

If this parameter is not provided, it is automatically inferred from the header.

Example

WEB

language string [2..3]

Description

Customer language settings for the translation of Payment Form fields and the language of email receipts sent for successful payments.

Example

en

force3ds boolean

Description

Routing payments flag for 3DS flow. Apple Pay tokens carry on-device cryptograms; Apple Pay handles authentication natively.

Example

true

order_metadata object

Description

Metadata is useful for storing additional, structured information about an object, consisting of up to 10 key-value pairs with a validation limit of 380 characters per field.

The callback notification returns an order_metadata from the order in each state.

Example

{"coupon_code": "NY2025", "partner_id": "123989"}

success_url string 255

Description

Provide this URL if you want to redirect a customer to your own Success Screen.

If you do not provide the URL, Solidgate directs customers to the Solidgate Success Screen.

Example

https://merchant.example/success

fail_url string 255

Description

Provide this URL if you want to redirect a customer to your own Fail Screen.

If you do not provide the URL, Solidgate directs customers to the Solidgate Fail Screen.

Example

https://merchant.example/fail

{
  "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 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 checkout update flow. Totals still come from checkout.line_items. Match the wallet payment sheet total with the invoicePreview event.

Select the Billing flow:

Product-based Billing 1.0 one-time product payment.
Provide product_id and merchant customer_account_id.

product_id string 36 Required

Description

Identifier of the predefined product in UUID v4 format.

Example

faf3b86a-1fe6-4ae5-84d4-ab0651d75db2

customer_account_id string 100 Required

Description

Merchant-defined customer ID for Billing 1.0.

This is not Billing 2.0 customer_id.

Example

4dad42f878

coupon_id string 36

Description

Coupon ID in UUID v4 format for a product discount.

Active only when product_id is present.

Example

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

Subscription 1.0 Billing 1.0 recurring subscription payment.
Provide product_id and merchant customer_account_id.

product_id string 36 Required

Description

Identifier of the predefined product in UUID v4 format.

Example

faf3b86a-1fe6-4ae5-84d4-ab0651d75db2

customer_account_id string 100 Required

Description

Merchant-defined customer ID for Billing 1.0.

This is not Billing 2.0 customer_id.

Example

4dad42f878

retry_attempt integer >=0

Description

Number of payment retries.

Example

1

coupon_id string 36

Description

Coupon ID in UUID v4 format for a product discount.

Active only when product_id is present.

Example

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

Subscription 2.0 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.

checkout object Required

Description

Recurring subscription payment parameters with one recurring line item, discounts, customer, and subscription data.

mode string Required

Description

Checkout flow type for a recurring subscription payment.

Use subscription as the value.

Example

subscription

customer_id string [6..100] Required

Description

Billing 2.0 customer ID in cust_… format.

Do not send merchant customer_account_id with checkout.

Example

cust_01KMG2ABYPF6XS5DMJQ817C429

merchant_reference string [1..100] Required

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

line_items array of objects Required

Description

Product line item applied to the subscription.

Pass exactly one recurring product. Multiple recurring products are not supported.
product_price_id string [1..100] Required

Description

Product price ID charged on this line.

Example

fa43b415-5522-4373-b026-a365562f9649

quantity integer [1..999999] Required

Description

Number of units of product_price_id on this line.

Example

1

discounts array of objects [0..1]

Description

Coupon applied to the subscription.

Provide either coupon_id or coupon_code not both.
coupon_id string [1..100]

Description

Coupon ID.

Cannot be used together with coupon_code.

Example

coup_abc123

coupon_code string [2..25]

Description

Coupon code entered by a customer.

Cannot be used together with coupon_id. Alphanumeric characters only.

Example

MAY2026

subscription_data object

Description

Subscription configuration.

description string [1..500]

Description

Subscription description.

Example

Premium plan annual

metadata object

Description

Custom string key/value pairs attached to the subscription.

At most 10 entries.

Example

{
  "campaign": "spring_2026",
  "channel": "ads"
}

trial object

Description

Trial period configuration.

type string Required

Description

Trial pricing model.

Allowed values are free and paid.

Example

paid

period object Required

Description

Trial duration.

value integer Required

Description

Trial duration in units.

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

Example

7

unit string Required

Description

Trial duration unit.

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

Example

day

amount integer [1..999999999]

Description

Trial price in minor units.

Used for paid trials.

Example

199

settle_interval integer [0..168]

Description

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

Example

48

Invoice Billing 2.0 one-time invoice checkout.
Provide a checkout object with mode as invoice and Billing customer_id.

checkout object Required

Description

One-time invoice payment parameters with line items discounts and customer details.

mode string Required

Description

Checkout flow type for a one-time invoice payment.

Use invoice as the value.

Example

invoice

customer_id string [6..100] Required

Description

Billing 2.0 customer ID in cust_… format.

Do not send merchant customer_account_id with checkout.

Example

cust_01KMG2ABYPF6XS5DMJQ817C429

merchant_reference string [1..100] Required

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

line_items array of objects Required

Description

Product line item applied to the invoice.

product_price_id string [1..100] Required

Description

Product price ID charged on this line.

Example

fa43b415-5522-4373-b026-a365562f9649

quantity integer [1..999999] Required

Description

Number of units of product_price_id on this line.

Example

2

description string [1..255]

Description

Per-line description shown on the invoice.

Example

Premium plan

discounts array of objects [0..1]

Description

Coupon applied to the cart.

Provide either coupon_id or coupon_code not both.
coupon_id string [1..100]

Description

Coupon ID.

Cannot be used together with coupon_code.

Example

coup_abc123

coupon_code string [2..25]

Description

Coupon code entered by a customer.

Cannot be used together with coupon_id. Alphanumeric characters only.

Example

MAY2026

Product-based

{
  "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"
}

Subscription 1.0

{
  "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"
}

Subscription 2.0

{
  "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"
}

Invoice

{
  "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 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

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.
Update the integrationType by 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.

applePayButtonParams

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

React

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>
  )
}

JavaScript

<div id="yourCustomContainerId"></div>
<script>
PaymentFormSdk.init({
  ...restData,
  applePayButtonParams: {
    buttonType: 'buy',
    buttonColor: 'black',
    containerId: 'yourCustomContainerId'
  }
});
</script>

Vue

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

Angular

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-->>'
  }
}

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:

Color

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.

Type

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.

enabled boolean

Description

Displays the Apple Pay button.

Example

false

Default

true

containerId string

Description

Identifier of container to place the Apple Pay button.

By default, if not set, the button is displayed above the form.

Example

yourCustomContainerId

Default

not set color string

Description

Color of the Apple Pay button.

Supported colors:

white-outline
black
white

Example

white-outline

Default

black

type string

Description

Type of the Apple Pay button.

Supported types:

check-out
add-money
buy
order
plain
reload
set-up
subscribe
top-up
continue
pay

Not supported types:

donate
support
rent
contribute
tip

Example

check-out

Default

plain

applePayButtonParams

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 .

Apple Pay button Print

Display button

Billing flow

Non-Safari browsers

Customization

Button position

Button styling

Button hiding

Apple payment sheet