Apple Pay

Apple Pay is a digital wallet payment method that enables your customers to pay via their Apple Wallet, without the need to type any card details. When your customers select this payment method, the Paybyrd payment gateway calls the Apple Pay SDK to display a native Apple payment modal.

How it works

Browser & device compatibility

The Apple Pay SDK identifies compatibility with the userAgent property, checking the customer’s device and browser type.

Apple Pay is supported by Apple devices running iOS, as well as desktop systems running Safari or other third-party browsers.
Apple Pay is not supported on Android devices or Samsung devices by default.

Payment flow

When the customer’s device or browser is supported, Paybyrd Checkout launches the native Apple Pay flow, enabling the customer to select a preferred card and pay with their configured Wallets.
When the customer’s device or browser not supported, the Paybyrd payment gateway calls the Apple Pay SDK to display a payment modal with a QR code. This enables customers to scan the code with an iPhone or iPad and pay with their configured Wallets.

Outcomes

Result	Behaviour
Success	Confirmation screen shown, customer redirected to `redirectUrl`.
Error / Declined	”Try again” screen shown. Customer can retry or pick another payment method.

How to integrate

You can integrate Apple Pay as a payment method in several ways. The first step is to manage domain validation, which is a hard requirement from Apple. This section guides you through the process.

Requirements

Requirement	Details
Registered domain	The exact domain must be validated with Apple via Paybyrd. See Domain Validation below.
HTTPS	Your domain must be served over HTTPS.
Web only	Apple Pay through Paybyrd is available via the Paybyrd Checkout on the web.

Domain validation

This step is mandatory. Apple Pay only functions in production on a domain that is validated by Apple.

Notify Paybyrd support — provide the exact domain where Paybyrd Checkout will run.
Paybyrd generates the validation file — the domain association file tied to your domain will be sent to you.

Upload the file to your server at this exact path:

/.well-known/apple-developer-merchantid-domain-association

Confirm to Paybyrd once the file is live and accessible.
Paybyrd completes verification with Apple and notifies you when Apple Pay is ready.

Paybyrd Checkout

When adding Apple Pay as an available payment method in an ecommerce setting, you need to create an order, then initiate a Checkout instance with the correct parameters.

Create an Order

Include "APPLE" in allowedPaymentMethods under the paymentOptions object when creating your order via the Paybyrd API:

curl --request POST \
 --url https://gateway.paybyrd.com/api/v2/orders \
 --header 'Accept: application/json' \
 --header 'Content-Type: application/json' \
 --header 'x-api-key: {your_api_key}' \
 --data '{
   "amount":"15.00",
   "currency":"EUR",
   "orderRef":"ABC123456",
   "expiresIn":24,
   "shopper":{
      "firstName":"John",
      "lastName":"Doe",
      "email":"john@doe.com",
      "phoneNumber":"+319999999921"
   },
   "orderOptions":{
      "redirectUrl":"https://your-site-url/payment-finished",
      "checkoutVersion": 2
   },
   "paymentOptions":{
      "allowedPaymentMethods": ["APPLEPAY"],
      "tokenOptions":{
         "customReference":"+319999999921"
      }
   }
}'

{
   "orderId":"13a8a157-81c9-46ea-84b4-2bef6daad3fa",
   "orderDate":"2026-02-24T17:45:27Z",
   "expiresAt":"2026-02-25T17:45:27Z",
   "checkoutUrl":"https://chk.paybyrd.com/chk_a321as123a",
   "checkoutKey":"eyJPcmRlcklkIjoiMzFhMDYzMmItODcxMy00NjIwLThiZjItMDdiN2UyZTk5MTRjIiwiT3JkZXJSZWYiOiI0MTAxMjA3MTU0IiwiUGVyc29uSWQiOjEwLCJMaXZlIjpmYWxzZSwiRW50aXR5SWQiOiIzMWEwNjMyYi04NzEzLTQ2MjAtOGJmMi0wN2I3ZTJlOTkeNGMiLCJBbW91bnQiOiI1MC4wMCIsIkN1cnJlbmN5IjoiRVVSIn0=",
   "status":"created",
   "isoAmount":15,
   "currency":"EUR",
   "orderRef":"ABC123456",
   "shopper":{
      "shopperId":"176b5023-1624-1d19-cdd2-c61b1be803b7",
      "firstName":"John",
      "lastName":"Doe",
      "email":"john@doe.com",
      "phoneNumber":"+319999999921"
   },
   "orderOptions":{
      "redirectUrl":"https://your-site-url/payment-finished",
      "culture":"en-US",
      "expiresIn":"24",
			"checkoutVersion": 2
   },
   "paymentOptions":{
	    "allowedPaymentMethods": ["APPLEPAY"],
      "tokenOptions":{
         "customReference":"+319999999921"
      }
   },
   "code":"BYRD200",
   "description":"Operation successfully completed"
}

You can combine Apple Pay with other methods, for example ["APPLEPAY", "CARD", "MBWAY"]. Each is shown or hidden based on device support and the parameter values you use.

Initiate a Checkout instance

You can initiate a Checkout instance in an iframe, or via a direct URL. In both cases, you can use the defaultPaymentMethod parameter to set Apple Pay as the default payment method. Simply add APPLEPAY as a value:

{
   "redirectUrl":"https://your-site-url/payment-finished",
   "locale":"en_US",
   "defaultPaymentMethod": "APPLEPAY"
}

Learn more about integrating Paybyrd Checkout and the available configuration options in the Paybyrd Checkout documentation.

Pay by Link

You can create a payment and provide it directly via a URL to your customers. Optionally, use the Payments API and configure the allowed payment methods programmatically.

curl --request POST \
 --url https://gateway.paybyrd.com/api/v2/payment \
 --header 'Accept: application/json' \
 --header 'Content-Type: application/json' \
 --header 'x-api-key: {your_api_key}' \
 --data '{
   "type":"DIGITALWALLET",
   "wallet":"APPLEPAY",
   "encryptedData":{
      "data":"qwsW672WX21Knduzd4cI5QzOCI3sbMidHuMxb4GnPwZpPKdh7OCf3c0dr6irOqDQvWG2iMYyCc4HAgH22n0kYj8BX1zIVqNvADMc7yIjM5lSuGPp3M45JU+H75Mw+sXnTL86yn69G4+c0JwIBmMw4cALzGWzg3h3HLX0/IYMQP9Sk9mvVYVlagCT3pDwQ2xFpjaF79AwP7UZxCkSrPsKmWIxlax2buG4PE5HgEDe5AWU04AFVvLNk4hJM8R6shMpOLbusAUL9OKn5Oimo5lzYN4lvNziEzfR8ImAWsV22TrOehqK0OQsAVbwblwDm3XyOcJQ2WDty11gdgdXLI9iOscS4Ik8U/P+wKCylOQFZs0hKX+QbFYhXgECY1eqzjGH5Ltdln4hJopU0w==",
      "header":{
         "publicKeyHash":"lWo3lMXY12OQNpy0XprCW5sDIor3EhWCKt9E748+7bc=",
         "ephemeralPublicKey":"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEJv9ngO1jNvlicQY9vL/9QlRCgWfHbfnx6Te1JZeYpn9ufe5Qlbte3ZP6SKHFTvM16p/3tfrNprE8n29NuHCwgw==",
         "transactionId":"1155d7ff481074b066bf85f37c534e3d28be89ca7161068d9c969cc17ccdefe8"
      },
      "version":"EC_v1"
   }
}'

You can find more details about this method in the Pay by Link documentation.

Going live

Request Apple Pay activation from Paybyrd Support
Provide your domain to Paybyrd Support
Receive the domain validation file from Paybyrd
Upload the file to /.well-known/apple-developer-merchantid-domain-association
Confirm the file is live to Paybyrd Support
Paybyrd completes Apple domain verification
Create an order and initiate a Checkout instance, or create a Pay by Link payment with the correct configuration parameters.

Accept Payments

Manage Payments

How it works

Browser & device compatibility

Payment flow

How to integrate

Requirements

Domain validation

Paybyrd Checkout

Pay by Link

Going live

​How it works

​Browser & device compatibility

​Payment flow

​How to integrate

​Requirements

​Domain validation

​Paybyrd Checkout

​Pay by Link

​Going live

How it works

Browser & device compatibility

Payment flow

How to integrate

Requirements

Domain validation

Paybyrd Checkout

Pay by Link

Going live