> ## Documentation Index > Fetch the complete documentation index at: https://developer.hellgate.io/llms.txt > Use this file to discover all available pages before exploring further. # Validate Apple Pay session > Complete Apple Pay's `onvalidatemerchant` exchange. When the customer opens the Apple Pay sheet in a browser, Apple fires `onvalidatemerchant`; your backend forwards the request here. Guardian performs the mTLS handshake with Apple using your merchant identity certificate and returns Apple's merchant session object verbatim, which you pass to `session.completeMerchantValidation(...)` in the browser. The `domain_name` must be a verified [Apple Pay domain](/products/guardian/tokens/wallet-tokens/apple-pay#prerequisites). Guardian reads your merchant identifier and display name from the [Apple Pay settings](/products/guardian/api-reference/wallet/get-settings); until those are uploaded the request returns `400` with the classifier `APPLE_PAY_NOT_CONFIGURED`. A request for an unregistered or unverified domain returns `422` with the classifier `APPLE_PAY_DOMAIN_NOT_VERIFIED`. If Apple rejects the validation, Guardian returns `502` with `APPLE_PAY_SESSION_ERROR`; if no active merchant identity certificate exists, the request returns `500` with `APPLE_PAY_NO_ACTIVE_CERTIFICATE`. ## OpenAPI ````yaml /products/guardian/openapi.yaml post /api/wallet/apple-pay/sessions openapi: 3.1.0 info: title: Guardian API version: '1.0' contact: name: Starfish GmbH & Co. KG email: support@hellgate.io url: https://hellgate.io/cpa/guardian license: name: Hellgate API Terms url: https://hellgate.io/terms-and-conditions servers: - url: https://{instance}.{env}.on-hellgate.cloud description: Managed instance of Guardian variables: instance: default: my-instance description: Your unique instance slug, provided during onboarding. env: default: eu1 description: Deployment environment (currently eu1). security: [] tags: - name: pci description: Management of card payment credentials under the ruling of PCI DSS. - name: network description: Management of network tokens and cryptograms for secure transactions. - name: generic description: Management of generic tokens and their schemas for various use cases. - name: metadata description: Inquiries for card metadata based on PAN, PCI tokens, or network tokens. - name: wallet description: >- Management of wallet tokens ingested from device wallets such as Google Pay. - name: apikey description: Management of API keys for service access. - name: webhook description: Management of webhooks for event notifications. - name: types description: Management of types for generic token schemas. paths: /api/wallet/apple-pay/sessions: post: tags: - wallet summary: Validate Apple Pay session description: > Complete Apple Pay's `onvalidatemerchant` exchange. When the customer opens the Apple Pay sheet in a browser, Apple fires `onvalidatemerchant`; your backend forwards the request here. Guardian performs the mTLS handshake with Apple using your merchant identity certificate and returns Apple's merchant session object verbatim, which you pass to `session.completeMerchantValidation(...)` in the browser. The `domain_name` must be a verified [Apple Pay domain](/products/guardian/tokens/wallet-tokens/apple-pay#prerequisites). Guardian reads your merchant identifier and display name from the [Apple Pay settings](/products/guardian/api-reference/wallet/get-settings); until those are uploaded the request returns `400` with the classifier `APPLE_PAY_NOT_CONFIGURED`. A request for an unregistered or unverified domain returns `422` with the classifier `APPLE_PAY_DOMAIN_NOT_VERIFIED`. If Apple rejects the validation, Guardian returns `502` with `APPLE_PAY_SESSION_ERROR`; if no active merchant identity certificate exists, the request returns `500` with `APPLE_PAY_NO_ACTIVE_CERTIFICATE`. operationId: wallet_apple_pay_session_create requestBody: content: application/json: schema: $ref: '#/components/schemas/apple_pay_session_request' responses: '200': description: Apple Pay merchant session, returned verbatim from Apple. content: application/json: schema: $ref: '#/components/schemas/apple_pay_session_response' '400': $ref: '#/components/responses/400_BadRequestError' '401': $ref: '#/components/responses/401_UnauthorizedError' '403': $ref: '#/components/responses/403_ForbiddenError' '422': $ref: '#/components/responses/422_ValidationError' '500': description: >- No active Apple Pay merchant identity certificate exists on this instance. content: application/json: schema: $ref: '#/components/schemas/ErrorGeneric' example: code: 500 message: >- The Apple Pay token could not be processed due to a server-side configuration issue. classifier: APPLE_PAY_NO_ACTIVE_CERTIFICATE '502': $ref: '#/components/responses/502_BadGatewayError' security: - bearerAuth: [] - APIKey: [] components: schemas: apple_pay_session_request: type: object properties: domain_name: type: string description: The fully-qualified merchant domain to validate. Must be verified. example: pay.example.com required: - domain_name apple_pay_session_response: title: Apple Pay Session type: object description: > Apple Pay merchant session JSON, returned verbatim from Apple. Treat it as opaque — pass it straight to `session.completeMerchantValidation(...)` without parsing or modifying it. The fields shown are illustrative; Apple controls the payload and may change it. additionalProperties: true example: epochTimestamp: 1769851200000 expiresAt: 1769853000000 merchantSessionIdentifier: SSH0A1B2C3D4E5F60718293A4B5C6D7E8F nonce: 0a1b2c3d merchantIdentifier: merchant.com.example displayName: Example Store initiative: web initiativeContext: pay.example.com signature: 308006092a864886f70d010702a0803080020101310f... operationalAnalyticsIdentifier: Example Store:merchant.com.example retries: 0 ErrorGeneric: type: object properties: code: $ref: '#/components/schemas/ErrorStatusCode' classifier: $ref: '#/components/schemas/ErrorClassifier' message: $ref: '#/components/schemas/ErrorMessage' ErrorValidation: type: object properties: code: $ref: '#/components/schemas/ErrorStatusCode' classifier: $ref: '#/components/schemas/ErrorClassifier' message: $ref: '#/components/schemas/ErrorMessage' validation_errors: type: array items: type: object properties: path: example: $.source.account_number type: string description: Json-path in the request which points to the validation error message: example: is required type: string description: Human readable validation message ErrorStatusCode: type: integer description: The corresponding HTTP status code for the error ErrorClassifier: type: string description: Technical code that helps to identify the error ErrorMessage: type: string description: Human readable representation of the error responses: 400_BadRequestError: description: Error response content: application/json: schema: $ref: '#/components/schemas/ErrorGeneric' example: code: 400 message: The request could not be handle due to invalid data classifier: BAD_REQUEST 401_UnauthorizedError: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorGeneric' example: code: 401 message: No valid means of authentication was provided classifier: UNAUTHORIZED 403_ForbiddenError: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorGeneric' example: code: 403 message: Not allowed to access this resource or feature classifier: FORBIDDEN 422_ValidationError: description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorValidation' example: code: 422 classifier: VALIDATION_ERROR message: Validation error validation_errors: - path: json-path message: human readable error message 502_BadGatewayError: description: A non-processable response was received from the upstream server content: application/json: schema: $ref: '#/components/schemas/ErrorGeneric' example: code: 502 message: Bad gateway classifier: BAD_GATEWAY securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- JWT bearer token obtained via the OAuth2 client-credentials grant from the platform Authentication API. The token's scopes gate the endpoints it may call, and its audience names the Guardian instance. This is the standard way to authenticate to Guardian. APIKey: type: apiKey name: x-api-key in: header description: >- Deprecated. Long-lived instance API key, sent as `x-api-key`. Existing integrations continue to work, but new ones should use the OAuth2 bearer token instead. ````