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