Skip to main content
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

Flowchart depicting Apple Pay payment flow
  1. 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.
  2. 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
ResultBehaviour
SuccessConfirmation 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

RequirementDetails
Registered domainThe exact domain must be validated with Apple via Paybyrd. See Domain Validation below.
HTTPSYour domain must be served over HTTPS.
Web onlyApple 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.
  1. Notify Paybyrd support — provide the exact domain where Paybyrd Checkout will run.
  2. Paybyrd generates the validation file — the domain association file tied to your domain will be sent to you.
  3. Upload the file to your server at this exact path: 
    	  /.well-known/apple-developer-merchantid-domain-association
  4. Confirm to Paybyrd once the file is live and accessible.
  5. Paybyrd completes verification with Apple and notifies you when Apple Pay is ready.

​
Integration

​
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.
  1. Create an Order
Include "APPLE" in allowedPaymentMethods under the paymentOptions object when creating your order via the Paybyrd API: 
curl --location -g --request POST '{{paybyrd-gateway}}/api/v2/orders
--header 'Accept: application/json'
--header 'Content-Type: application/json'
--header 'X-Api-Key: <your-API-key>'
--data '
curl --request POST \
     --url https://gateway.paybyrd.com/api/v2/payment \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --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.
  1. 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.
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 {{paybyrd-gateway}}/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

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