| Payment Status |
| STATUS_SUCCESS | Payment Authorized Successfully The payment was successfully authorized. Call completePayment(STATUS_SUCCESS) to dismiss the Apple Pay sheet with a success animation and proceed with order fulfillment. | Success | Common | T0 |
| STATUS_FAILURE | Payment Authorization Failed The payment authorization failed for an unspecified reason (e.g., gateway rejection, processor error). The Apple Pay sheet is dismissed and the customer is prompted to try another method. | Error, Decline | Common | T2 |
| STATUS_INVALID_BILLING_POSTAL_ADDRESS | Invalid Billing Postal Address The billing postal address provided by the customer is invalid for this merchant. The payment sheet remains open so the customer can correct their billing address. Deprecated in Apple Pay JS v3 (use ApplePayError instead). | Error | Occasional | T0 |
| STATUS_INVALID_SHIPPING_POSTAL_ADDRESS | Invalid Shipping Postal Address The shipping postal address is invalid or unserviceable (e.g., PO boxes not allowed, unsupported country). The payment sheet remains open so the customer can update their address. Deprecated in Apple Pay JS v3. | Error | Occasional | T0 |
| STATUS_INVALID_SHIPPING_CONTACT | Invalid Shipping Contact The shipping contact information (e.g., phone number, email) provided is invalid. The payment sheet stays open for correction. Deprecated in Apple Pay JS v3. | Error | Occasional | T0 |
| STATUS_PIN_REQUIRED | PIN Required The payment requires a PIN to be entered by the cardholder. Primarily used in Europe for PIN-authenticated transactions. | Pending | Occasional | T0 |
| STATUS_PIN_INCORRECT | PIN Incorrect The PIN entered by the cardholder is incorrect. The customer must re-enter the correct PIN to proceed. | Error, Decline | Occasional | T0 |
| STATUS_PIN_LOCKOUT | PIN Lockout The cardholder has exceeded the allowed PIN attempts and the card is locked. The customer must contact their bank to unlock the card. | Decline, Error | Rare | T2 |
| shippingContactInvalid | Shipping Contact Invalid A field in the shipping contact is invalid (e.g., phone number, email, or name). Used in Apple Pay JS v3+ completeShippingContactSelection and completePayment to indicate which contact field is invalid. | Error | Occasional | T0 |
| billingContactInvalid | Billing Contact Invalid A field in the billing contact is invalid (e.g., incorrect billing name, postal address field). Used in completePayment with ApplePayError to surface specific billing field errors on the payment sheet. | Error | Occasional | T0 |
| addressUnserviceable | Address Unserviceable The shipping address is valid but cannot be serviced by the merchant (e.g., merchant does not ship to this country or region). The payment sheet prompts the customer to choose a different address. | Error | Occasional | T0 |
| couponCodeInvalid | Coupon Code Invalid The coupon code entered on the Apple Pay sheet is not valid. Used in completeCouponCodeChange to indicate the coupon code is unrecognized or incorrectly formatted. | Error | Occasional | T0 |
| couponCodeExpired | Coupon Code Expired The coupon code entered on the Apple Pay sheet has expired and can no longer be applied. | Error | Occasional | T0 |
| unknown | Unknown Error An unknown or unclassified error occurred. Used as a catch-all when the error does not fit a specific category. Log for debugging and prompt the customer to retry. | Error | Occasional | T0 |
| PKPaymentAuthorizationStatus.success | Authorization Success The payment was successfully authorized and processed. Returned from the merchant server to PKPaymentAuthorizationResult to close the payment sheet with a success checkmark. | Success | Common | T0 |
| PKPaymentAuthorizationStatus.failure | Authorization Failure The payment authorization failed. Returned to PKPaymentAuthorizationResult when the merchant server rejects the transaction. May include specific PKPaymentError objects for detailed field-level feedback. | Error, Decline | Common | T2 |
| PKPaymentError.unknownError | Unknown Payment Error An unspecified error occurred during the payment flow. Use as a fallback when no specific error code applies. Code = -1. | Error | Occasional | T0 |
| PKPaymentError.shippingContactInvalidError | Shipping Contact Invalid Error The shipping contact information (phone, email, name, or address) submitted is invalid. Specify which field is invalid using PKPaymentErrorKey.contactFieldUserInfoKey. Code = 1. | Error | Occasional | T0 |
| PKPaymentError.billingContactInvalidError | Billing Contact Invalid Error The billing contact information submitted is invalid. Use PKPaymentErrorKey.contactFieldUserInfoKey to specify the invalid field (e.g., name, street, postal code). Code = 2. | Error | Occasional | T0 |
| PKPaymentError.shippingAddressUnserviceableError | Shipping Address Unserviceable The shipping address is valid but the merchant cannot service it (e.g., out-of-range delivery zone, unsupported country). Prompts the customer to select an alternative address. Code = 3. | Error | Occasional | T0 |
| SESSION_NOT_STARTED | Session Not Started An ApplePaySession could not be created. Common reasons: the page is not served over HTTPS, the domain is not registered with Apple, or the user's device does not support Apple Pay. | Error | Occasional | T1 |
| MERCHANT_VALIDATION_FAILED | Merchant Validation Failed The merchant validation step (completeMerchantValidation) failed. The validationURL request to Apple's servers returned an error, or the merchant identity certificate is invalid or expired. The session is terminated. | Error | Occasional | T1 |
| PAYMENT_NOT_PROCESSED | Payment Not Processed Apple Pay cannot process the payment. Common causes: the merchant domain is not verified with Apple, the merchant identity certificate has expired, or the merchant session request contains an incorrect initiativeContext. | Error | Occasional | T1 |
| USER_CANCELLED | User Cancelled The customer dismissed the Apple Pay sheet without authorizing the payment. The oncancel event is fired. No charge has been made; treat as an abandoned checkout. | Info | Common | T0 |
| APPLE_PAY_NOT_AVAILABLE | Apple Pay Not Available Apple Pay is not available on this device/browser. ApplePaySession.canMakePayments() returns false. Merchant should hide the Apple Pay button and offer alternative payment methods. | Info | Common | T3 |
| APPLE_PAY_NO_ACTIVE_CARD | No Active Card in Wallet The user's device supports Apple Pay but has no active payment card provisioned. ApplePaySession.canMakePaymentsWithActiveCard() returns false. Show the Apple Pay button with a 'set up' CTA or offer alternative methods. | Info | Occasional | T3 |
| INVALID_PAYMENT_TOKEN | Invalid Payment Token The payment token received from Apple Pay is malformed or could not be decrypted by the merchant's Payment Processing Certificate. Verify the certificate configuration and token handling. | Error | Occasional | T1 |
| PAYMENT_TOKEN_AMOUNT_MISMATCH | Payment Token Amount Mismatch The amount in the Apple Pay token does not match the amount submitted to the payment processor. Ensure the amount set in the ApplePayPaymentRequest matches the amount sent to the gateway. | Error | Occasional | T1 |
| DOMAIN_NOT_VERIFIED | Domain Not Verified The merchant's domain has not been verified with Apple. The apple-developer-merchantid-domain-association file must be hosted at /.well-known/ on the merchant's domain and registered in the Apple Developer portal. | Error | Occasional | T1 |
| UNAUTHORIZED_MERCHANT | Unauthorized to Process for Merchant The API call is not authorized to process transactions on behalf of the merchant ID. Ensure the correct merchant ID and API credentials are used, and that the domain is linked to the merchant identity certificate. | Error | Occasional | T1 |
| DECLINED_FRAUD | Declined – Fraud Suspected The issuing bank or payment processor declined the Apple Pay authorization due to suspected fraud. The customer should contact their bank. | Decline, Error | Occasional | T2 |
| Decline Codes |
| STATUS_FAILURE | Payment Authorization Failed The payment authorization failed for an unspecified reason (e.g., gateway rejection, processor error). The Apple Pay sheet is dismissed and the customer is prompted to try another method. | Error, Decline | Common | T2 |
| STATUS_PIN_INCORRECT | PIN Incorrect The PIN entered by the cardholder is incorrect. The customer must re-enter the correct PIN to proceed. | Error, Decline | Occasional | T0 |
| STATUS_PIN_LOCKOUT | PIN Lockout The cardholder has exceeded the allowed PIN attempts and the card is locked. The customer must contact their bank to unlock the card. | Decline, Error | Rare | T2 |
| PKPaymentAuthorizationStatus.failure | Authorization Failure The payment authorization failed. Returned to PKPaymentAuthorizationResult when the merchant server rejects the transaction. May include specific PKPaymentError objects for detailed field-level feedback. | Error, Decline | Common | T2 |
| DECLINED_INSUFFICIENT_FUNDS | Declined – Insufficient Funds The issuing bank declined the Apple Pay token because the card account lacks sufficient funds. The customer should use a different card or fund the account. | Decline | Common | T3 |
| DECLINED_CARD_EXPIRED | Declined – Card Expired The card associated with the Apple Pay token has expired. The customer must add a new or updated card to their Wallet. | Decline | Common | T3 |
| DECLINED_FRAUD | Declined – Fraud Suspected The issuing bank or payment processor declined the Apple Pay authorization due to suspected fraud. The customer should contact their bank. | Decline, Error | Occasional | T2 |
| DECLINED_DO_NOT_HONOR | Declined – Do Not Honor Generic issuer decline. The issuing bank declined the Apple Pay transaction without a specific reason. The customer should contact their bank. | Decline | Common | T2 |
| Error Codes |
| STATUS_FAILURE | Payment Authorization Failed The payment authorization failed for an unspecified reason (e.g., gateway rejection, processor error). The Apple Pay sheet is dismissed and the customer is prompted to try another method. | Error, Decline | Common | T2 |
| STATUS_INVALID_BILLING_POSTAL_ADDRESS | Invalid Billing Postal Address The billing postal address provided by the customer is invalid for this merchant. The payment sheet remains open so the customer can correct their billing address. Deprecated in Apple Pay JS v3 (use ApplePayError instead). | Error | Occasional | T0 |
| STATUS_INVALID_SHIPPING_POSTAL_ADDRESS | Invalid Shipping Postal Address The shipping postal address is invalid or unserviceable (e.g., PO boxes not allowed, unsupported country). The payment sheet remains open so the customer can update their address. Deprecated in Apple Pay JS v3. | Error | Occasional | T0 |
| STATUS_INVALID_SHIPPING_CONTACT | Invalid Shipping Contact The shipping contact information (e.g., phone number, email) provided is invalid. The payment sheet stays open for correction. Deprecated in Apple Pay JS v3. | Error | Occasional | T0 |
| STATUS_PIN_INCORRECT | PIN Incorrect The PIN entered by the cardholder is incorrect. The customer must re-enter the correct PIN to proceed. | Error, Decline | Occasional | T0 |
| STATUS_PIN_LOCKOUT | PIN Lockout The cardholder has exceeded the allowed PIN attempts and the card is locked. The customer must contact their bank to unlock the card. | Decline, Error | Rare | T2 |
| shippingContactInvalid | Shipping Contact Invalid A field in the shipping contact is invalid (e.g., phone number, email, or name). Used in Apple Pay JS v3+ completeShippingContactSelection and completePayment to indicate which contact field is invalid. | Error | Occasional | T0 |
| billingContactInvalid | Billing Contact Invalid A field in the billing contact is invalid (e.g., incorrect billing name, postal address field). Used in completePayment with ApplePayError to surface specific billing field errors on the payment sheet. | Error | Occasional | T0 |
| addressUnserviceable | Address Unserviceable The shipping address is valid but cannot be serviced by the merchant (e.g., merchant does not ship to this country or region). The payment sheet prompts the customer to choose a different address. | Error | Occasional | T0 |
| couponCodeInvalid | Coupon Code Invalid The coupon code entered on the Apple Pay sheet is not valid. Used in completeCouponCodeChange to indicate the coupon code is unrecognized or incorrectly formatted. | Error | Occasional | T0 |
| couponCodeExpired | Coupon Code Expired The coupon code entered on the Apple Pay sheet has expired and can no longer be applied. | Error | Occasional | T0 |
| unknown | Unknown Error An unknown or unclassified error occurred. Used as a catch-all when the error does not fit a specific category. Log for debugging and prompt the customer to retry. | Error | Occasional | T0 |
| PKPaymentAuthorizationStatus.failure | Authorization Failure The payment authorization failed. Returned to PKPaymentAuthorizationResult when the merchant server rejects the transaction. May include specific PKPaymentError objects for detailed field-level feedback. | Error, Decline | Common | T2 |
| PKPaymentError.unknownError | Unknown Payment Error An unspecified error occurred during the payment flow. Use as a fallback when no specific error code applies. Code = -1. | Error | Occasional | T0 |
| PKPaymentError.shippingContactInvalidError | Shipping Contact Invalid Error The shipping contact information (phone, email, name, or address) submitted is invalid. Specify which field is invalid using PKPaymentErrorKey.contactFieldUserInfoKey. Code = 1. | Error | Occasional | T0 |
| PKPaymentError.billingContactInvalidError | Billing Contact Invalid Error The billing contact information submitted is invalid. Use PKPaymentErrorKey.contactFieldUserInfoKey to specify the invalid field (e.g., name, street, postal code). Code = 2. | Error | Occasional | T0 |
| PKPaymentError.shippingAddressUnserviceableError | Shipping Address Unserviceable The shipping address is valid but the merchant cannot service it (e.g., out-of-range delivery zone, unsupported country). Prompts the customer to select an alternative address. Code = 3. | Error | Occasional | T0 |
| SESSION_NOT_STARTED | Session Not Started An ApplePaySession could not be created. Common reasons: the page is not served over HTTPS, the domain is not registered with Apple, or the user's device does not support Apple Pay. | Error | Occasional | T1 |
| MERCHANT_VALIDATION_FAILED | Merchant Validation Failed The merchant validation step (completeMerchantValidation) failed. The validationURL request to Apple's servers returned an error, or the merchant identity certificate is invalid or expired. The session is terminated. | Error | Occasional | T1 |
| PAYMENT_NOT_PROCESSED | Payment Not Processed Apple Pay cannot process the payment. Common causes: the merchant domain is not verified with Apple, the merchant identity certificate has expired, or the merchant session request contains an incorrect initiativeContext. | Error | Occasional | T1 |
| INVALID_PAYMENT_TOKEN | Invalid Payment Token The payment token received from Apple Pay is malformed or could not be decrypted by the merchant's Payment Processing Certificate. Verify the certificate configuration and token handling. | Error | Occasional | T1 |
| PAYMENT_TOKEN_AMOUNT_MISMATCH | Payment Token Amount Mismatch The amount in the Apple Pay token does not match the amount submitted to the payment processor. Ensure the amount set in the ApplePayPaymentRequest matches the amount sent to the gateway. | Error | Occasional | T1 |
| DOMAIN_NOT_VERIFIED | Domain Not Verified The merchant's domain has not been verified with Apple. The apple-developer-merchantid-domain-association file must be hosted at /.well-known/ on the merchant's domain and registered in the Apple Developer portal. | Error | Occasional | T1 |
| CERTIFICATE_ERROR | Payment Processing Certificate Error The Payment Processing Certificate is missing, expired, or not associated with the API credential being used. Re-upload and activate the certificate in the Apple Developer Portal. | Error | Occasional | T1 |
| UNAUTHORIZED_MERCHANT | Unauthorized to Process for Merchant The API call is not authorized to process transactions on behalf of the merchant ID. Ensure the correct merchant ID and API credentials are used, and that the domain is linked to the merchant identity certificate. | Error | Occasional | T1 |
| DECLINED_FRAUD | Declined – Fraud Suspected The issuing bank or payment processor declined the Apple Pay authorization due to suspected fraud. The customer should contact their bank. | Decline, Error | Occasional | T2 |
USA
