Apple Pay Troubleshooting

Common error scenarios and solutions for Apple Pay integration with Onerway.

Prerequisites

• Applied for Apple Pay payment through Onerway
• Onerway has configured Apple Pay for your account
• Completed basic configuration (see Account Setup)
• Understand the payment flow (see Payment Flow)

Common Problems

Problem Categories

1. Apple Pay button not displayed
   • See Device Support Issues
2. Apple Pay button displayed but payment form appears briefly then disappears
   • See Device Support Issues and Merchant Validation Failure
3. Payment appears incomplete after confirmation
   • See Merchant Validation Failure and Payment Processing Errors

Common Error Scenarios

Test Card Issues

Test Card Issues

Common Causes:

• Test card configuration issues
• Test card has expired
• Test card was declined

Solutions:

1. Verify Test Environment:

   • Confirm using a Tester Apple ID (see Create Sandbox Apple Account)
   • Verify the test account's country/region:
     • Go to Settings > General > Language & Region and ensure the region is set to: Australia, Canada, France, Hong Kong, Ireland, Italy, Japan, New Zealand, Russia, Singapore, Spain, Taiwan, United Kingdom, or United States
     • If not, switch to a supported region like United States or United Kingdom

2. Use Valid Test Cards:

   • Use official Apple Pay test cards (see Test Card List)
   • Ensure test cards have not expired and all information is correct
   • Verify test cards are successfully added to Apple Wallet

Device Support Issues

Device Does Not Support Apple Pay

Common Causes:

• Using non-Safari browsers (Chrome, Firefox, etc.)

• Running in non-HTTPS environment

• Device doesn't support Apple Pay (non-Apple devices, iOS below 11.2)

• User hasn't added payment cards to Apple Wallet

• Country/region not supported for Apple Pay

Solutions:

1. User Guidance:

   • Prompt users to use Safari browser
   • Guide users through adding payment cards to Apple Wallet
   • Provide device compatibility information page

2. Product Strategy:

   • Set alternative payment methods as primary options
   • Only display Apple Pay on compatible devices (see Session Initialization: ApplePaySession.canMakePayments())
   • Provide clear payment method selection interface

3. User Experience:

   • Hide unavailable payment options
   • Display user-friendly error messages
   • Ensure alternative payment flows work seamlessly

4. Country/Region Support:

   • Verify Apple Pay availability for the user's country or region
   • If the country/region is unsupported, users generally cannot complete Apple Pay payments

Merchant Validation Failure

Merchant Validation Failure

Common Causes:

• Merchant identity certificate configuration error (merchant-owned mode only)
• Domain verification file missing or inaccessible
• Merchant identifier configuration issues
• Domain name passed by validation interface doesn't match configured domain (merchant-owned mode only)
• Backend validation interface errors

Solutions:

1. Certificate and Configuration Issues:

   • Contact Onerway: Certificate expiration or configuration errors require Onerway to regenerate certificates
   • Verify Domain Verification File: Ensure /.well-known/apple-developer-merchantid-domain-association file exists and is accessible (see Account Setup: Domain Verification)
   • Validate Domain Name: Ensure initiativeContext passed by validation interface matches configured domainName (merchant-owned mode only)
   • Confirm HTTPS: Ensure website uses valid SSL certificate

2. Environment Configuration:

   • Production Environment: Use correct production merchant identifier
   • Test Environment: Use sandbox environment configuration
   • Domain Allowlist: Ensure current domain is registered in Apple Pay configuration

3. Monitoring and Maintenance:

   • Set up certificate expiration alerts
   • Regularly verify domain verification file accessibility
   • Monitor validation failure rates

4. Error Handling:

   • Display clear error messages to users
   • Fall back gracefully to alternative payment methods
   • Contact Onerway technical support when needed

Payment Processing Errors

Payment Authorization or Processing Failure

Common Causes:

• Payment processing certificate status abnormal
• Payment processing errors
• Onerway configuration issues

Solutions:

1. Get Support:
   • Contact Onerway technical support for immediate assistance

Technical Self-Check Checklist

Environment Configuration Self-Check

Complete the following self-check steps before contacting technical support:

Basic Environment Check

• HTTPS Verification: Confirm website uses HTTPS protocol
• SSL Rating: Confirm A-grade rating on SSL Labs
• Domain Verification File: Confirm /.well-known/apple-developer-merchantid-domain-association is accessible
• Browser Compatibility: Confirm testing in Safari browser

Code Implementation Check

• Device Support Detection: ApplePaySession.canMakePayments() returns true
• Session Creation: new ApplePaySession(3, paymentRequest) successfully creates session
• Event Binding: onvalidatemerchant and onpaymentauthorized events are correctly bound
• Error Handling: oncancel and exception handling are implemented

Configuration Verification Check

• Merchant ID: Confirm using correct merchant identifier (see Account Setup)
• Payment Method Configuration: Configuration from Payment Methods Query API is correct
• Domain Consistency: Frontend domain matches backend validation domain
• Certificate Status: Confirm certificates aren't expired and correctly configured

Debugging Tools and Methods

Browser Debugging

// Check Apple Pay API availability
console.log('Apple Pay API available:', !!window.ApplePaySession); 
console.log('Can make payments:', ApplePaySession.canMakePayments()); 

// Check payment method support
ApplePaySession.canMakePaymentsWithActiveCard('your-merchant-id')
  .then(canMakePayments => {
    console.log('Can make payments with active card:', canMakePayments); 
  });

Network Request Check

• Merchant Validation Request: Check network requests triggered by onvalidatemerchant event
• Payment Processing Request: Check Onerway API calls triggered by onpaymentauthorized event
• Response Status: Confirm all API requests return correct status codes
• Error Logs: Check browser console and network panel for error messages

Common Debugging Commands

# Check domain verification file
curl -I https://yourdomain.com/.well-known/apple-developer-merchantid-domain-association

# Check SSL configuration
openssl s_client -connect yourdomain.com:443 -servername yourdomain.com

# Verify DNS resolution
nslookup yourdomain.com

Getting Technical Support

Prepare Information for Onerway Support

1. Basic Information:

   • Merchant number and integration mode (merchant-owned/proxy mode)
   • Specific time and environment where problem occurred (test/production)
   • User device information (iOS version, Safari version)

2. Technical Details:

   • Complete error logs and console output
   • Detailed network request information (request/response content)
   • Completed self-check checklist results

3. Reproduction Steps:

   • Detailed steps to reproduce the problem
   • Comparison of expected vs actual behavior
   • Problem occurrence frequency and impact scope

Related Documentation Links

• Account Setup - Certificate and domain configuration guide
• Session Initialization - SDK loading and device detection
• Payment Initiation - ApplePaySession creation and configuration
• Merchant Validation - Merchant validation process guide
• Payment Authorization - Payment processing flow guide
• Payment Flow - Complete payment flow sequence diagram
• Test Card Information - Apple Pay test card list