Handling Errors

Provide clear, actionable guidance when problems occur during checkout or payment processing, so users can resolve problems quickly and complete their transaction.

Data Validation

Your app or website can respond to user input when the payment sheet appears, when the user changes certain field values on the payment sheet, and after the user authenticates the transaction. Use these opportunities to check for data entry problems and to provide clear and consistent messaging.

When data is invalid, red system-provided error messaging calls attention to relevant fields on the payment sheet. The user can choose a field to view additional details and resolve the problem. Provide customized error messages for the detail view that appears when the user chooses a problematic field.

For developer guidance, see PKPaymentAuthorizationViewControllerDelegate (iOS, watchOS) and Apple Pay on the Web (web).

Note For privacy reasons, your app or website has limited access to data until the user attempts to authorize a transaction. Prior to authorization, only the card type and a redacted shipping address are accessible. It’s critical to report errors to the user when authorization fails, but to the extent possible, your app should also attempt to validate available information and report problems before authorization.

Avoid forcing compliance with your business logic. Design a data validation process that’s intelligent enough to ignore irrelevant data and infer missing data whenever possible. For example, if your app requires a five-digit zip code but the user enters a Zip+4 code, ignore the additional digits rather than asking for a correction. Accept state names in multiple formats (a user should be able to enter California or CA without producing an error). Handle phone numbers in multiple formats (with and without dashes, with and without a country code).

Provide accurate status reporting to the system. When a problem occurs, it’s essential that your app or website accurately indicate the type of problem so the system can show the most relevant error message on the payment sheet. This is done by accompanying your custom error message with the correct status code. For developer guidance, see PKPaymentError (iOS, watchOS) and Apple Pay Status Codes (web).

Succinctly and specifically describe the problem when data is invalid or incorrectly formatted. Reference the relevant field and indicate exactly what’s expected. For example, if the user enters an invalid zip code, instead of showing “Address is invalid”, show a specific message like “Zip code doesn’t match city”. If the shipping address is unserviceable, indicate why—“Shipping not available for this state”. Use noun phrases with sentence-style capitalization and no ending punctuation. Keep messages short to avoid truncation—strive for 128 characters or less.

Inform the user when a required field is empty. Call attention to a blank required field with a short descriptive message like “Zip code is required”.

Payment Processing

Handle interruptions correctly. A user-driven event like a cancellation or a system-driven event like a timeout could cause an interruption in the payment flow, resulting in the payment sheet being dismissed. When such an event occurs, you must cancel any in-progress payment. After the payment sheet dismisses, the user can restart the process by tapping or clicking the Apple Pay button again. For developer guidance, see PKPaymentAuthorizationViewControllerDelegate (iOS, watchOS) and oncancel (web).