> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ionicfi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Register a domain for Apple Pay

> Verifies the Apple Pay association file at
`/.well-known/apple-developer-merchantid-domain-association`, then
registers the domain. Expected validation or provider rejection is
returned as HTTP 200 with `apple_pay.status` set to `failed` and an
actionable `apple_pay.error`; inspect the resource state on every
response.




## OpenAPI

````yaml /openapi/web_domains.yaml post /web_domains/{id}/apple_pay
openapi: 3.0.3
info:
  title: Ionic Web Domains API
  version: '2026-09-02'
  description: |
    Manage the website origins allowed to embed Ionic Checkout and register
    eligible domains for Apple Pay.

    Domains are scoped to the Account and to the secret key's test or live
    mode. Use a direct Account secret key; these endpoints do not accept the
    `Ionic-Account` header. A domain is an origin—scheme, host, and optional
    non-default port—not a full page URL. Public domains must use HTTPS; HTTP
    is accepted only for loopback development origins.
servers:
  - url: '{baseUrl}/v1'
    variables:
      baseUrl:
        default: https://api.ionicfi.com
        description: API base URL for your environment.
security:
  - secretKey: []
tags:
  - name: Web Domains
    description: Origins authorized for embedded checkout and browser SDK calls.
  - name: Apple Pay Domains
    description: Apple Pay registration state for an authorized web domain.
paths:
  /web_domains/{id}/apple_pay:
    post:
      tags:
        - Apple Pay Domains
      summary: Register a domain for Apple Pay
      description: |
        Verifies the Apple Pay association file at
        `/.well-known/apple-developer-merchantid-domain-association`, then
        registers the domain. Expected validation or provider rejection is
        returned as HTTP 200 with `apple_pay.status` set to `failed` and an
        actionable `apple_pay.error`; inspect the resource state on every
        response.
      operationId: registerWebDomainForApplePay
      parameters:
        - $ref: '#/components/parameters/WebDomainId'
      responses:
        '200':
          description: The web domain with its latest Apple Pay registration state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebDomain'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/WriteForbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/Unavailable'
      security:
        - secretKey:
            - web_domains:write
components:
  parameters:
    WebDomainId:
      name: id
      in: path
      required: true
      description: Ionic web domain ID.
      schema:
        type: string
        pattern: ^wd_[0-9A-Za-z]{14}$
  schemas:
    WebDomain:
      type: object
      additionalProperties: false
      required:
        - id
        - object
        - domain
        - livemode
        - apple_pay
      properties:
        id:
          type: string
          pattern: ^wd_[0-9A-Za-z]{14}$
        object:
          type: string
          enum:
            - web_domain
        domain:
          type: string
          description: Canonical browser origin.
          example: https://shop.example.com
        livemode:
          type: boolean
        apple_pay:
          $ref: '#/components/schemas/ApplePayDomainState'
        created_at:
          type: integer
          format: int64
          description: Unix epoch seconds.
    ApplePayDomainState:
      type: object
      additionalProperties: false
      required:
        - status
      properties:
        status:
          type: string
          enum:
            - not_registered
            - pending
            - registered
            - failed
        registered_at:
          type: integer
          format: int64
          description: Unix epoch seconds of the successful registration.
        error:
          type: string
          description: >-
            Actionable reason supplied when the latest registration attempt
            failed.
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
            message:
              type: string
  responses:
    BadRequest:
      description: The domain, identifier, or request body is invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    WriteForbidden:
      description: A direct Account key with `web_domains:write` is required.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The web domain was not found for this Account and key mode.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Too many requests.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalError:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unavailable:
      description: Apple Pay domain registration is temporarily unavailable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    secretKey:
      type: http
      scheme: bearer
      description: 'An Account secret key (`sk_…`) sent as `Authorization: Bearer <key>`.'

````