You can choose to configure your Apple Pay integration using the payments APIs. This method requires you to first register your domains and subdomains in the Toast developer portal. For more information, see Registering and verifying a merchant domain.
|
Important |
|
Apple Pay® is currently only available for Toast platform integrations on Apple’s Safari web browser. |
The following procedure is an overview of how to configure and
accept Apple Pay payments using the payments APIs. This procedure is
separate from using the Toast developer portal to configure and enable
Apple Pay as a payment method for use in the hosted checkout
iframe.
-
Register your domain for Apple Pay. You must register your domain and subdomains in the Toast developer portal. For more information, see Configuring Apple Pay in the Toast developer portal.
-
Host the static domain verification file on all the domains and subdomains that will accept Apple Pay. For more information, see Hosting the static domain verification file.
-
Build your Apple Pay integration that guests use to complete Apple Pay payments.
-
Create a payment intent. You create the payment intent when the checkout page loads onto your website. For more information, see Creating a payment intent.
-
Your customer selects the Apple Pay button on your checkout page. This opens and displays the Apple Pay payment sheet on your checkout page and creates an
ApplePaySession. For more information, seeApplePaySession.When your integration displays the Apple Pay payment sheet, the Apple Pay JavaScript API automatically calls the
onvalidatemerchantevent handler. Theonvalidatemerchantevent handler validates your identity and confirms that your domain is registered with Apple and is authorized to process Apple Pay payments. If the validation is successful, the payment sheet appears on the checkout page for the customer to review and complete the transaction. -
Create an Apple Pay payment session by sending a
POSTrequest to the/digital-wallet-broker/v1/wallets/apple-pay/payment-sessionendpoint of the digital wallet broker API. This returns an Apple Pay payment session. The Apple Pay payment session manages various payment actions, such as verifying the merchant’s identity and handling customer actions.The Apple Pay payment session invokes the
completeMerchantValidationfunction, which completes merchant validation and displays the payment sheet to the customer. -
When your customer approves the transaction, this invokes the Apple Pay JavaScript SDK
onpaymentauthorizedevent handler. This event handler returns anApplePayPaymentobject. TheApplePayPaymentprovides information about the customer’s payment credentials. -
Create a payment method by sending a
POSTrequest to the/v1/payment-methodsendpoint of the payment methods API. Include theApplePayPaymentobject in the request body. -
Confirm the payment intent by sending a
POSTrequest to the/v1/payment-intents/{paymentIntentId}/confirmendpoint of the payment intents API.If the payment intent was successfully confirmed, call Apple Pay JavaScript SDK
completePaymentwithSTATUS_SUCCESS. If the payment intent was not successfully confirmed, callcompletePaymentwithSTATUS_FAILURE. For more information, see Apple Pay status codes.
After you have registered your domains and subdomains and hosted the static domain verification file, the next step is to build the Apple Pay payment interface. The Apple Pay payment interface is a web interface that customers use to complete Apple Pay payments. You use the Apple Pay JS API to build the interface and implement the following functions:
-
Determine whether a customer’s ordering device supports Apple Pay payments and can display Apple Pay payment controls.
-
Handle the interface events that occur when a customer makes an Apple Pay payment on your ordering interface.
Once you have successfully registered as an Apple Pay web merchant
under the Toast platform, you can retrieve valid Apple Pay payment
sessions through the Toast platform. You must successfully create an
Apple Pay payment session to receive an ApplePayPayment
you can use to create a payment method. The following sections describe
how to authorize Apple Pay transactions in your integration.
To authorize an Apple Pay transaction, you must first check if the Apple Pay JavaScript API is available and enabled in your integration. This ensures that your website only displays the Apple Pay button on supported browsers. To check if Apple Pay is available:
-
Check if
ApplePaySessionexists in a browser window. For more information, see Checking for Apple Pay availability. -
Check if
canMakePayments()returns true. For more information, seecanMakePayments.
If both conditions are met, you can display the Apple Pay button on your checkout page.
After you have confirmed that Apple Pay is available and enabled
in your integration, your customer's web browser will validate your
merchant identity, retrieve the Apple Pay payment session, and display
the Apple Pay payment sheet to the customer. The Apple Pay payment
sheet displays the customer’s linked payment cards, the purchase
amount, shipping options (if applicable), and contact information. To
display the Apple Pay payment sheet, you must create an
ApplePayPaymentRequest to attach to the Apple Pay payment
session. For more information, see ApplePayPaymentRequest.
The next step to authorizing an Apple Pay transaction is to
define the onvalidatemerchant event handler. The
onvalidatemerchant event handler is automatically invoked
after the Apple Pay payment session has begun. For more information,
see onvalidatemerchant.
You must also define the onpaymentauthorized event
handler. The onpaymentauthorized event handler is
automatically invoked after the customer successfully authorizes the
Apple Pay payment using Face ID, Touch ID, or a passcode. For more
information, see onpaymentauthorized.
You can define secondary event handlers to react to your customer’s actions in the Apple Pay payment sheet. You can define secondary event handlers for the following action types:
|
Note |
|
This list is not comprehensive. |
-
Handling payment method updates
-
Handling coupons
-
Handling shipping contact updates
-
Handling shipping method updates
For more information, see ApplePaySession.
|
Important |
|
Certain Apple Pay JavaScript SDK web browser behaviors such as opening a payment dialog require a user gesture (for example, a button select) to avoid unwanted actions such as unauthorized payments. Apple Pay payments must be initiated by a user gesture to ensure proper security and functionality. |
To initiate an Apple Pay session, define the
onvalidatemerchant event handler to send a
POST request to the
/digital-wallet-broker/v1/wallets/apple-pay/payment-session
endpoint of the digital wallet broker API. Include the
Toast-Restaurant-External-ID as a header parameter in the
request to specify the GUID of the Toast POS location. In the request
body, include the domain and the
validationURL. This returns an
ApplePaySession object. For more information, see
ApplePaySession.
Example request body to initiate an Apple Pay session
{
"validationURL": "https://apple-pay-gateway-cert.apple.com/paymentservices/paymentSession", 
"domain": "toasty.com", 
"paymentMethodDomainId": "d57daa6c-5384-431c-962f-a1b7551fbf49", 
"sessionSecret": "string" 
}|
The Apple Pay gateway URL. The
|
|
|
The internet domain name used to submit an Apple Pay payment. The domain must match a domain you registered for your Apple Pay payment integration. |
|
|
The identifier of the merchant domain. You can retrieve
the |
|
|
A unique and randomized identifier for the payment intent. For more information, see Creating a payment intent. |
Example response body to initiate an Apple Pay session
"string" |
For more information, see Providing merchant validation. |
|
Note |
|
You can create the payment intent before or after your customer selects the Apple Pay button. Toast support recommends you create the payment intent before your customer selects the Apple Pay button. |
To accept an Apple Pay payment on your checkout page, you need to
create a payment intent. To create a payment intent for an Apple Pay
transaction, send a POST request to the /v1/payment-intents
endpoint of the payment intents API to return a PaymentIntentResponse
object and a sessionSecret. Include the
Toast-Restaurant-External-ID as a header parameter in the
request to specify the GUID of the Toast POS location that you are
creating a payment intent for.
Example request body to create a payment intent for an Apple Pay transaction
{
"amount": 1000,
"currency": "USD",
"externalReferenceId": "73edc827-0c18-485f-b581-1ef79f93b940",
"captureMethod": "MANUAL",
"email": "john.smith@email.com" 
}|
The payment amount in minor currency units represented as a
positive integer. The minimum amount is 0.01 (represented as .01).
In this example, |
|||
|
The supported currency types are:
|
|||
|
The identifier for the payment intent generated by the Toast
POS location or your integration. The
|
|||
|
Controls when funds are captured:
|
|||
|
The customer's email address. The customer's email address only needs to be provided once when you create or confirm the payment intent. |
Example response body to create a payment intent for an Apple Pay transaction
{
"id": "86bbcf0c-b483-4bbc-81bf-c2a9cd2baa2c",
"externalReferenceId": "73edc827-0c18-485f-b581-1ef79f93b940",
"sessionSecret": "PI_86bbcf0c-b483-4bbc-81bf-c2a9cd2baa2c_SECRET_EqYQ5^CgQWc4J?KBwq2jfv&Ov",
"amount": 1000,
"currency": "USD",
"captureMethod": "MANUAL",
"status": "REQUIRES_PAYMENT_METHOD",
"paymentMethodId": null,
"creationDate": "2023-09-29T16:42:36.239579Z",
"usage": null,
"customerId": null,
"amountDetails": {
"tip": 0
},
"email": "john.smith@email.com",
"paymentMethodConfigurationDetails": {
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
},
"latestPayment": null,
"offSession": false,
"standingInstructionType": null,
"mandateId": null
}|
The identifier of the payment intent. |
|
|
The identifier for the payment intent generated by the Toast
POS location or your integration. The
|
|
|
A unique identifier for the payment intent that you use to create a payment method. |
|
|
The status of the payment intent. Values are:
For more information, see Payment intent statuses. |
|
|
The date and time the payment intent was created in ISO 8601
format. Toast support recommends that you store the
|
After you create the payment intent and determine if Apple Pay is
available, call applePaySession.begin(), to begin the
merchant validation process. When you call the begin()
method, this displays the Apple Pay payment sheet on your checkout page
and initiates the merchant validation process by calling the
onvalidatemerchant event handler and any other secondary
handlers. For more information, see begin.
To create a payment method, define the
onpaymentauthorized event handler. Your integration sends a
POST request to the /v1/payment-methods
endpoint of the payment methods API. Include the
Toast-Restaurant-External-ID as a header parameter in the
request to specify the GUID of the Toast POS location that you are
creating a payment method for. In the request body, set the
type value to CARD and include the
Card object, which contains information about the payment
card.
Include the following header parameters:
-
Toast-Session-Secret: The unique and randomized identifier for the payment intent. This is returned in the response to create a payment intent. -
Toast-Idempotency-Key: An integration-generated universally unique identifier (UUID) that is used to recognize retries of the same request.
Example request body to create a payment method for an Apple Pay transaction
{
"type": "CARD",
"card": {
"wallet": {
"type": "APPLE_PAY",
"applePayPayment": JSON.stringify(event.payment)
}
}
}|
The type of payment method. |
|
|
Digital wallet attributes. These attributes are required
when creating an Apple Pay payment method. When present, the
payment method |
|
|
An object that contains the customer’s payment credentials.
For more information, see |
Example response body to create a payment method for an Apple Pay transaction
{
"id": "f718c101-70e4-45fe-8fc1-67ba0a12a8c5",
"type": "CARD",
"usage": null,
"card": {
"firstSix": "411111",
"lastFour": "1111",
"expiry": {
"month": "12",
"year": "27"
},
"brand": "VISA",
"type": "VISA",
"fingerprint": "e19f9942-942b-4716-a45c-6ee69225970d",
"funding": "Debit",
[contents omitted]
}
}|
The identifier of the payment method. Include the
|
|
|
The payment method details for a |
Once you successfully created a payment method for an Apple Pay
payment, you must confirm the payment intent in the
onpaymentauthorized event handler.
The last step to completing an Apple Pay payment is to confirm the payment intent. Confirming the payment intent represents your customer’s intention to pay the amount with the attached payment method. If the payment intent is successfully confirmed, the Toast platform authorizes the Apple Pay payment.
Example request body to confirm a payment intent for an Apple Pay transaction
{
"paymentMethodId": "f718c101-70e4-45fe-8fc1-67ba0a12a8c5",
"sessionSecret": "PI_86bbcf0c-b483-4bbc-81bf-c2a9cd2baa2c_SECRET_EqYQ5^CgQWc4J?KBwq2jfv&Ov",
"email": "john.smith@email.com"
}
Example response body to confirm a payment intent for an Apple Pay transaction
{
"id": "86bbcf0c-b483-4bbc-81bf-c2a9cd2baa2c",
"externalReferenceId": "73edc827-0c18-485f-b581-1ef79f93b940",
"sessionSecret": "PI_86bbcf0c-b483-4bbc-81bf-c2a9cd2baa2c_SECRET_EqYQ5^CgQWc4J?KBwq2jfv&Ov",
"amount": 1000,
"currency": "USD",
"captureMethod": "MANUAL",
"status": "REQUIRES_CAPTURE",
"paymentMethodId": "f718c101-70e4-45fe-8fc1-67ba0a12a8c5",
"creationDate": "2023-09-29T16:42:36.239579Z",
"usage": null,
"customerId": "4b2dfc5a-88a3-11ee-b9d1-0242ac120002",
"amountDetails": {
"tip": 0
},
"email": "john.smith@email.com",
"paymentMethodConfigurationDetails": {
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
},
"latestPayment": {
"card": {
"brand": "VISA",
"lastFour": "1111",
"expiry": {
"month": "12",
"year": "27"
}
}
},
"offSession": false,
"standingInstructionType": null,
"mandateId": null,
"lastPaymentError": {
"type": "CARD_DECLINED",
"code": "DECLINE" 
}
}|
The unique identifier of the payment intent. |
|
|
The status of the payment intent. For more information, see Payment intent statuses. |
|
|
Payment card details associated with the latest payment intent. |
|
|
Details about the payment card transaction failure. The
|
|
|
The type of payment card error. Available values are:
|
|
|
Additional information about why the payment card was
declined. This value is only returned if the If the payment intent was successfully confirmed, call
|