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

Choose your payment scenario to see the fields it requires. Payment 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

Product-based payment 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

Customer ID in the merchant’s system.

Example

4dad42f878

Subscription payment product_price_id string 36 Required

Description

Price ID of the predefined product. Use get product prices to obtain it.

Example

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

customer_account_id string 100 Required

Description

Customer ID in the merchant’s system.

Example

4dad42f878

order_id string 255 Required

Description

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

Example

123456

currency string 3 Required

Description

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

Example

USD

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

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.

If not provided, the Apple Payment Sheet falls back to the default merchant name configured for the channel.

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

retry_attempt integer >=0

Description

Number of payment retries.

Should be provided for the subscription workflow.

Example

1

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

Payment

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

Product-based payment

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

Subscription payment

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

Vanilla JS

<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 change the name, you need to pass the apple_pay_merchant_name parameter in the paymentIntent object.

Apple Pay button Print

Display button

Non-Safari browsers

Customization

Button position

Button styling

Button hiding

Apple payment sheet