Apple Pay merchant validation
Apple Pay is available only for Optimizely Configured Commerce through the Payment Service. Apple Pay requires Apple to validate your merchant identity when the payment sheet opens. The shopper cannot authorize payment until this validation completes. When Apple Pay is enabled, the storefront asks Optimizely Configured Commerce to request this validation. Apple Pay provides a validation URL when it starts merchant validation. Configured Commerce sends the request to Apple's gateway with your merchant identity certificate. It then returns Apple's response, called the merchant session, to the browser.
Since 5.2.2610, Configured Commerce contacts only Apple gateway hosts. This restriction stops a signed-in shopper from using the endpoint to make the server connect to another host.
Prerequisites
Before you use the endpoint, make sure the following are in place:
- Payment Service is your payment gateway, and Apple Pay is enabled. The Enable Apple Pay setting applies only to the Payment Service gateway, and you need the ISC_System or ISC_Implementer role to change it. See Enable Apple Pay for Payment Service for the full setup.
- The Apple Pay settings group contains your merchant ID, merchant name, merchant certificate, and certificate password.
Merchant validation endpoint
The storefront sends the merchant validation request to the following endpoint. The endpoint requires an authenticated storefront session and the Enable Apple Pay payment setting.
POST /api/v1/applepay/sessionThe request body contains the following properties:
- validationUrl – The validation URL that Apple provides for the merchant validation event. This property is required.
- domainName – The domain name of the storefront that requests the Apple Pay session.
The Apple Pay certificate, merchant ID, and merchant name come from the Apple Pay settings group in the Admin Console. Do not send them in the request.
The following request body asks Configured Commerce to validate the merchant for a storefront domain. Replace VALIDATION_URL with the validation URL that Apple provides, and replace STOREFRONT_DOMAIN with the domain of your storefront.
{
"validationUrl": "VALIDATION_URL",
"domainName": "STOREFRONT_DOMAIN"
}Allowed validation URLs
Configured Commerce accepts a validationUrl only when all of the following are true:
- The URL starts with https://.
- The host is exactly one of the allowed gateway hosts. Configured Commerce rejects subdomains, hosts that only start or end with a gateway name, and a trailing dot.
- The URL does not include a port (including :443), user information (user@), spaces, or control characters such as line breaks.
Configured Commerce allows the following Apple gateway hosts:
- apple-pay-gateway.apple.com – Production (global)
- cn-apple-pay-gateway.apple.com – Production (China region)
- apple-pay-gateway-cert.apple.com – Sandbox testing (global)
- cn-apple-pay-gateway-cert.apple.com – Sandbox testing (China region)
Apple lists these hosts in Setting Up Your Server. Use the sandbox hosts for development and sandbox testing only. The host comparison is not case-sensitive.
If you call the endpoint from custom storefront code, pass the validationUrl exactly as Apple provides it. Configured Commerce rejects any other value.
Endpoint responses
The endpoint returns the following responses:
Condition | Status | Response |
|---|---|---|
Apple validated the merchant | 200 | The merchant session as application/json. |
Enable Apple Pay is off | 400 | Apple Pay is not enabled |
validationUrl is missing | 400 | Validation URL is required |
validationUrl is not an allowed URL | 400 | Invalid validation URL. |
The Apple gateway returns an error or a redirect | 502 | Apple Pay merchant validation failed. |
An unexpected error occurs | 500 | No details. |
A rejected validationUrl never causes an outbound request, and Configured Commerce does not load the merchant certificate for it. The response does not include the submitted URL, the gateway's response, or exception details.
Configured Commerce does not follow redirects when it contacts the gateway. A redirect from a gateway host cannot carry the merchant certificate to another host. The endpoint returns 502 for a redirect.
📘 Note IApplePayService.ValidateSessionAsync applies the same host check. If you call it directly, it returns a failed result for a disallowed validationUrl. The result has the error message Invalid validation URL., and the service does not contact Apple.
A custom IApplePayService implementation does not inherit the check. Validate the host in your implementation, for example with ApplePayGatewayUrlValidator.TryValidate.
Changes in 5.2.2610
Configured Commerce 5.2.2610 changes the endpoint in the following ways:
- It accepts only the allowed gateway hosts and does not follow redirects.
- It returns generic error messages. Earlier versions returned the status code and response text from the gateway.
- It writes the details that it does not return to the application log.
The default Spire checkout passes the validationURL value from the Apple Pay event unchanged, so it needs no update. If your custom storefront code reads the gateway's error text from this endpoint, update it to handle the generic messages.
Troubleshoot merchant validation
Configured Commerce writes the following details to the application log instead of returning them to the browser:
- Rejected URL – A warning that starts with Rejected Apple Pay merchant validation URL. It lists the user profile ID, user name, guest status, and submitted URL. Configured Commerce removes HTML tags from the URL and limits it to 2,000 characters.
- Gateway error – A warning that starts with Apple Pay merchant validation against. It lists the gateway host, status code, reason phrase, and response text.
- Unexpected error – An error with the message Apple Pay session validation failed. and the exception.
If every merchant validation returns Invalid validation URL. after you upgrade to 5.2.2610 or later:
- Find the Rejected Apple Pay merchant validation URL warning in the application log.
- Compare the submitted URL with the allowed gateway hosts.
- If the URL uses a host that is not in the list, contact Optimizely Support.