---
title: Apple Pay merchant validation
slug: commerce-composable-modules/payment-gateway/apple-pay-merchant-validation
createdAt: 2026-10-23T09:00:00.000Z
---

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](docId\:e1UKqsJE-SNW5iYrxZx4G) 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.

```text
POST /api/v1/applepay/session
```

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

```json
{
  "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](https://developer.apple.com/documentation/applepayontheweb/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.

:::hint{type="info"}
**📘 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:

1. Find the `Rejected Apple Pay merchant validation URL` warning in the application log.
2. Compare the submitted URL with the allowed gateway hosts.
3. If the URL uses a host that is not in the list, contact Optimizely Support.