Apple Pay button

Sign in Hub
Get help
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
anchor

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.
  2. Complete the domain verification by adding the domain in the Developers section of Solidgate Hub .

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
  • Domain 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"
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

{
  "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",
  "customer_first_name": "John",
  "customer_last_name": "Snow",
  "ip_address": "8.8.8.8",
  "geo_country": "USA",
  "platform": "WEB",
  "language": "en",
  "retry_attempt": 1,
  "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

{
  "order_id": "123456",
  "product_price_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",
  "customer_first_name": "John",
  "customer_last_name": "Snow",
  "ip_address": "8.8.8.8",
  "geo_country": "USA",
  "platform": "WEB",
  "language": "en",
  "retry_attempt": 1,
  "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
Collect country-specific customer data like billing address, tax ID, and phone number to meet issuer requirements and improve approvals. certain regions, including India.

Non-Safari browsers
anchor

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
anchor

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
anchor

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

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
anchor

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
anchor

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
anchor

Solidgate Payment Form gives you access to customize merchant name label on the Apple Payment Sheet Reference .

To change the name, you need to pass the apple_pay_merchant_name parameter in the paymentIntent object.

Looking for help? Contact us
Stay informed with Changelog