Apple Pay Payment Processing API

openapi: 3.2.0
info:
  title: Apple Pay Payment Token Payment Processing 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/
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
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
components:
  schemas:
    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
    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
    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
    ApplePayPaymentSubmission:
      type: object
      required:
      - token
      properties:
        token:
          $ref: '#/components/schemas/PaymentToken'
        billingContact:
          $ref: '#/components/schemas/PaymentContact'
        shippingContact:
          $ref: '#/components/schemas/PaymentContact'
    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
    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
    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
    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
externalDocs:
  description: Payment Token Format Reference
  url: https://developer.apple.com/documentation/passkit/apple_pay/payment_token_format_reference