Apple Pay Payment Token API

openapi: 3.1.0
info:
  title: Apple Pay Payment Token API
  description: >-
    Server-side specification for processing Apple Pay payment tokens. When a
    customer authorizes an Apple Pay payment, the client application receives
    an encrypted payment token containing the payment credential. The merchant
    server or payment service provider must decrypt and process this token to
    complete the transaction. This specification documents the payment token
    structure and the merchant server endpoints for receiving and processing
    payment tokens.
  version: '1.0'
  contact:
    name: Apple Developer Support
    url: https://developer.apple.com/support/apple-pay/
  termsOfService: https://developer.apple.com/apple-pay/acceptable-use-guidelines/
externalDocs:
  description: Payment Token Format Reference
  url: https://developer.apple.com/documentation/passkit/apple_pay/payment_token_format_reference
servers:
  - url: https://{merchantServer}
    description: Merchant payment processing server
    variables:
      merchantServer:
        default: api.example.com
        description: The merchant's payment processing server hostname
tags:
  - name: Payment Processing
    description: Endpoints for receiving and processing Apple Pay payment tokens
  - name: Payment Status
    description: Endpoints for checking payment transaction status
paths:
  /payments/apple-pay:
    post:
      operationId: processApplePayPayment
      summary: Process an Apple Pay payment
      description: >-
        Receives an Apple Pay payment token from the client application,
        decrypts the payment data using the merchant's payment processing
        certificate, and submits the payment credentials to the payment
        processor or acquiring bank for authorization.
      tags:
        - Payment Processing
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplePayPaymentSubmission'
      responses:
        '200':
          description: Payment processed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResult'
        '400':
          description: Invalid payment token or request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentError'
        '401':
          description: Authentication required
        '422':
          description: Payment declined or could not be processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentError'
        '500':
          description: Internal server error
  /payments/apple-pay/{transactionId}:
    get:
      operationId: getPaymentStatus
      summary: Apple Pay Get payment transaction status
      description: >-
        Retrieves the status of a previously submitted Apple Pay payment
        transaction.
      tags:
        - Payment Status
      parameters:
        - $ref: '#/components/parameters/transactionId'
      responses:
        '200':
          description: Transaction status retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResult'
        '404':
          description: Transaction not found
components:
  parameters:
    transactionId:
      name: transactionId
      in: path
      required: true
      description: Unique transaction identifier returned from payment processing
      schema:
        type: string
  schemas:
    ApplePayPaymentSubmission:
      type: object
      required:
        - token
      properties:
        token:
          $ref: '#/components/schemas/PaymentToken'
        billingContact:
          $ref: '#/components/schemas/PaymentContact'
        shippingContact:
          $ref: '#/components/schemas/PaymentContact'
    PaymentToken:
      type: object
      description: >-
        The Apple Pay payment token containing encrypted payment credentials.
        This token is generated by the Secure Element on the user's device
        after biometric or passcode authorization.
      required:
        - paymentData
        - paymentMethod
        - transactionIdentifier
      properties:
        paymentData:
          $ref: '#/components/schemas/PaymentData'
        paymentMethod:
          $ref: '#/components/schemas/PaymentMethod'
        transactionIdentifier:
          type: string
          description: >-
            A unique identifier for the payment transaction, generated by
            Apple Pay
    PaymentData:
      type: object
      description: >-
        Encrypted payment data. The structure depends on the token version
        (EC_v1 or RSA_v2). The data field contains the encrypted payment
        credentials that must be decrypted using the merchant's payment
        processing certificate.
      required:
        - data
        - signature
        - header
        - version
      properties:
        data:
          type: string
          description: >-
            Base64-encoded encrypted payment data. When decrypted, contains
            the payment credential (DPAN, expiration, cryptogram)
        signature:
          type: string
          description: >-
            Base64-encoded signature of the payment and header data. Used
            to verify the token was generated by Apple on a genuine device
        header:
          $ref: '#/components/schemas/PaymentDataHeader'
        version:
          type: string
          enum:
            - EC_v1
            - RSA_v2
          description: >-
            Version of the payment token. EC_v1 uses Elliptic Curve
            Diffie-Hellman. RSA_v2 uses RSA encryption. Most integrations
            use EC_v1
    PaymentDataHeader:
      type: object
      description: Header fields for the payment data encryption
      properties:
        applicationData:
          type: string
          description: >-
            SHA-256 hash of the applicationData property of the original
            PKPaymentRequest, hex-encoded
        ephemeralPublicKey:
          type: string
          description: >-
            Base64-encoded ephemeral public key for EC_v1 token version.
            Used with the merchant private key to derive the symmetric
            encryption key via ECDH
        wrappedKey:
          type: string
          description: >-
            Base64-encoded wrapped key for RSA_v2 token version. The
            symmetric key encrypted with the merchant's RSA public key
        publicKeyHash:
          type: string
          description: >-
            Base64-encoded SHA-256 hash of the merchant's payment processing
            certificate public key. Used to identify which certificate
            was used
        transactionId:
          type: string
          description: >-
            A hex-encoded transaction identifier generated on the device.
            Matches the transactionIdentifier in the outer token
    DecryptedPaymentData:
      type: object
      description: >-
        The decrypted contents of the payment data field, containing the
        actual payment credentials to submit to the payment processor
      properties:
        applicationPrimaryAccountNumber:
          type: string
          description: >-
            Device-specific Primary Account Number (DPAN). This is a
            tokenized card number, not the actual card number
        applicationExpirationDate:
          type: string
          description: >-
            Expiration date of the DPAN in YYMMDD format
        currencyCode:
          type: string
          description: >-
            ISO 4217 numeric currency code
        transactionAmount:
          type: number
          description: Transaction amount
        cardholderName:
          type: string
          description: Cardholder name if provided
        deviceManufacturerIdentifier:
          type: string
          description: >-
            Hex-encoded identifier for the device manufacturer
        paymentDataType:
          type: string
          enum:
            - '3DSecure'
            - 'EMV'
          description: >-
            The type of payment data. 3DSecure for in-app and web payments,
            EMV for contactless payments at terminals
        paymentData:
          type: object
          description: >-
            The payment cryptogram and related data
          properties:
            onlinePaymentCryptogram:
              type: string
              description: >-
                Base64-encoded payment cryptogram for online/in-app
                payments (3DSecure type)
            eciIndicator:
              type: string
              description: >-
                ECI indicator. Common values are 05 (Visa) and 07
                (Mastercard) for fully authenticated transactions
            emvData:
              type: string
              description: >-
                Base64-encoded EMV payment structure for contactless
                payments (EMV type)
            encryptedPINData:
              type: string
              description: >-
                Base64-encoded encrypted PIN data, if applicable
    PaymentMethod:
      type: object
      description: Information about the payment card used
      properties:
        displayName:
          type: string
          description: >-
            A localized description of the payment card suitable for
            display, e.g. "Visa 1234"
        network:
          type: string
          enum:
            - Visa
            - Mastercard
            - Amex
            - Discover
            - JCB
            - ChinaUnionPay
            - Interac
            - PrivateLabel
            - Eftpos
            - CartesBancaires
            - iD
            - QuicPay
            - Suica
            - Mada
            - Bancomat
            - Bancontact
            - Girocard
          description: The payment card network
        type:
          type: string
          enum:
            - debit
            - credit
            - prepaid
            - store
          description: The type of card (debit, credit, prepaid, or store)
        paymentPass:
          type: object
          description: >-
            Information about the payment pass in the user's Wallet
          properties:
            primaryAccountIdentifier:
              type: string
              description: Primary account identifier for the payment pass
            primaryAccountNumberSuffix:
              type: string
              description: Last four digits of the primary account number
            deviceAccountIdentifier:
              type: string
              description: Device account identifier
            deviceAccountNumberSuffix:
              type: string
              description: Last four digits of the device account number
    PaymentContact:
      type: object
      description: Billing or shipping contact information
      properties:
        phoneNumber:
          type: string
          description: Contact phone number
        emailAddress:
          type: string
          format: email
          description: Contact email address
        givenName:
          type: string
          description: First name
        familyName:
          type: string
          description: Last name
        phoneticGivenName:
          type: string
          description: Phonetic first name
        phoneticFamilyName:
          type: string
          description: Phonetic last name
        addressLines:
          type: array
          items:
            type: string
          description: Street address lines
        subLocality:
          type: string
          description: Sub-locality (e.g., neighborhood)
        locality:
          type: string
          description: City or locality
        postalCode:
          type: string
          description: Postal or ZIP code
        subAdministrativeArea:
          type: string
          description: Sub-administrative area (e.g., county)
        administrativeArea:
          type: string
          description: State or province
        country:
          type: string
          description: Country name
        countryCode:
          type: string
          description: ISO 3166-1 alpha-2 country code
    PaymentResult:
      type: object
      description: Result of payment processing
      properties:
        transactionId:
          type: string
          description: Unique transaction identifier
        status:
          type: string
          enum:
            - authorized
            - captured
            - declined
            - error
            - pending
          description: Payment transaction status
        authorizationCode:
          type: string
          description: Authorization code from the payment processor
        amount:
          type: number
          description: Authorized or captured amount
        currency:
          type: string
          description: ISO 4217 currency code
        processedAt:
          type: string
          format: date-time
          description: Timestamp when the payment was processed
    PaymentError:
      type: object
      properties:
        code:
          type: string
          description: Error code
        message:
          type: string
          description: Human-readable error message
        details:
          type: string
          description: Additional error details