--- title: "TN3176: Troubleshooting Apple Pay payment processing issues" framework: technotes role: article role_heading: Article path: technotes/tn3176-troubleshooting-apple-pay-payment-processing-issues --- # TN3176: Troubleshooting Apple Pay payment processing issues Diagnose errors that occur when processing Apple Pay payments, identify common causes, and explore potential solutions. ## Overview Overview This technote covers debugging common Apple Pay payment processing issues. When an Apple Pay payment is requested by your app or website, Apple sends an encrypted payment token to you to verify its signature, decrypt its payment data, and validate the transaction. Often, these payment processing issues are caused by an invalid payment processing certificate, or by mishandling payment data by you or your payment service provider (PSP). Possible reasons for payment service provider errors while handling the Apple Pay payment token Payment token validation that fail for your PSP are often due to an issue with your payment processing certificate or the format of your token. In either case, your PSP may be able to provide additional insight. Please confirm the following with your PSP: The merchant ID value used throughout Apple Pay must be identical to the one you created in your Apple Developer account. If it is different, Apple will not be able to to decrypt the payment data. The merchant ID is associated with the correct payment processing certificate. The payment processing certificate is in an active state in your Apple Developer account. The merchantCapabilities array of the ApplePayPaymentRequest contains only supports3DS. Your PSP is sending the authorization message in the format required by each payment network. For more information about configuring your merchant identifier (ID) and certificates required for Apple Pay, see Configuring Your Environment. Possible reasons for payment token decryption errors You validate a transaction by verifying the signature, decrypting the payment data, and verifying additional transaction details. A payment token’s payment data is encrypted using either elliptic curve cryptography (ECC) or RSA encryption. The encryption algorith used is based on the merchant capabilities of the initial payment request. The payment token can be decrypted by the merchant with the certificate private key or by the PSP on behalf of the merchant. For China mainland, decrypt via RSA; otherwise decrypt via ECC. If you experience payment token-related decryption issues, please confirm the following: The PSP routes the payment to the correct payment network. The tokenization of the payment data doesn’t take too long or hasn’t timed out. The decrypted data is a valid JSON object. You receive a parseable JSON output when you attempt to decrypt a payment token, indicating a possible a key mismatch. No payment with the same transactionId shows as processed, indicating a transaction you’ve already credited. The merchant ID that you share with PSP is identical to the one you created in your Apple Developer account. For more information, see Payment token format reference. Possible reasons for payment token processing errors Once decrypted, the payment token is passed to the PSP for processing. If you experience payment token-related processing issues, please confirm the following: The cryptogram format is valid. For example, the merchantCapabilities property includes supports3DS (as well as supportsEMV, if you support China Union Pay transactions). Your PSP has assigned the correct Electronic Commerce Indicator (ECI) values for the transcation. Your certificate signing request (CSR) Apple uses to encrypt the payment token was generated for the correct environment (sandbox or production). and not mismatched. You aren’t reusing a previously processed payment token. Cryptograms are single-use and cannot be used over multiple transactions. Revision History 2024-06-25 First published. ## See Also ### Latest - [TN3210: Optimizing your app for iPhone Mirroring](technotes/tn3210-optimizing-your-app-for-iphone-mirroring.md) - [TN3211: Resolving SwiftUI source incompatibilities for State and ContentBuilder](technotes/tn3211-resolving-swiftui-source-incompatibilities-for-state-and-contentbuilder.md) - [TN3212: Adopting gesture recognizers for Sidecar touch support](technotes/tn3212-adopting-gesture-recognizers-for-sidecar-touch-support.md) - [TN3208: Preparing your app’s launch screen to meet App Store requirements](technotes/tn3208-preparing-your-apps-launch-screen-to-meet-app-store-requirements.md) - [TN3205: Low-latency communication with RDMA over Thunderbolt](technotes/tn3205-low-latency-communication-with-rdma-over-thunderbolt.md) - [TN3206: Updating Apple Pay certificates](technotes/tn3206-updating-apple-pay-certificates.md) - [TN3179: Understanding local network privacy](technotes/tn3179-understanding-local-network-privacy.md) - [TN3190: USB audio device design considerations](technotes/tn3190-usb-audio-device-design-considerations.md) - [TN3194: Handling account deletions and revoking tokens for Sign in with Apple](technotes/tn3194-handling-account-deletions-and-revoking-tokens-for-sign-in-with-apple.md) - [TN3193: Managing the on-device foundation model’s context window](technotes/tn3193-managing-the-on-device-foundation-model-s-context-window.md) - [TN3115: Bluetooth State Restoration app relaunch rules](technotes/tn3115-bluetooth-state-restoration-app-relaunch-rules.md) - [TN3192: Migrating your iPad app from the deprecated UIRequiresFullScreen key](technotes/tn3192-migrating-your-app-from-the-deprecated-uirequiresfullscreen-key.md) - [TN3151: Choosing the right networking API](technotes/tn3151-choosing-the-right-networking-api.md) - [TN3111: iOS Wi-Fi API overview](technotes/tn3111-ios-wifi-api-overview.md) - [TN3191: IMAP extensions supported by Mail for iOS, iPadOS, and visionOS](technotes/tn3191-imap-extensions-supported-by-mail.md)