Payments

English

简体中文

English

简体中文

Theme

Apple Pay Integration Setup ​

This guide covers the essential setup steps required before implementing Apple Pay payment processing. Complete these requirements based on your chosen integration mode.

Prerequisites ​

Before beginning the setup process, ensure you have:

  • Merchant Account: An active Onerway merchant account with Apple Pay processing capability
  • HTTPS Domain: Production domain with valid SSL certificate
  • Integration Mode Decision: Clear understanding of your chosen integration approach

Integration Mode Quick Reference

  • Merchant-Owned Account Mode: Requires an Apple Developer account and self-managed certificates
  • Onerway Proxy Mode: Leverages Onerway's centralized certificate infrastructure

Merchant-Owned Account Mode Setup ​

1. Apple Developer Account Setup ​

Create Merchant Identifier ​

Important

Skip this step if using an existing Merchant ID.

  1. Access Apple Developer Console:

  2. Create New Merchant ID:

    • Click the "+" next to Identifier
    • Select Merchant IDs → Click Continue
    • Enter Description and Identifier (format: merchant.com.yourcompany.appname)
    • Click Register and record the Merchant ID

Configure Payment Processing Certificate ​

Certificate Setup Process

Onerway generates payment processing certificates. You'll need to upload the Onerway-provided certificate to your Apple Developer account.

  1. Request Certificate from Onerway:

    • Submit your Merchant ID to the Onerway technical integration team
    • Onerway generates a merchant-specific payment processing certificate

  2. Upload Certificate to Apple Developer Console:

    • Access your Merchant ID configuration
    • Navigate to Apple Pay Payment Processing Certificate → Click Create Certificate
    • Select No for "Will payments be processed exclusively in China mainland?" (Onerway processes internationally)
    • Upload the Certificate Signing Request (CSR) file provided by Onerway

Configure Merchant Identity Certificate (Optional) ​

When to Configure

Only configure merchant identity certificates if handling merchant validation server-side. Skip this step to use Onerway's centralized validation infrastructure.

  1. Certificate Creation Process:

    • Navigate to Apple Pay Merchant Identity Certificate → Click Create Certificate
    • Generate CSR file following Apple's CSR creation guide
    • Upload CSR file and download the resulting certificate

  2. Implementation Requirements:

2. Domain Registration & Verification ​

Domain Registration Process ​

Simplified Domain Management

For simplified domain management, skip self-registration and use Onerway-provided domain verification files.

  1. Self-Managed Domain Registration:

    • In Merchant ID configuration, click Add Domain under Merchant Domains
    • Enter your Apple Pay domain
    • Download domain verification file apple-developer-merchantid-domain-association

  2. Domain Verification File Deployment:

    bash
    # Deploy verification file to exact path:
https://yourdomain.com/.well-known/apple-developer-merchantid-domain-association

# Verify HTTPS accessibility returns HTTP 200 status
curl -I https://yourdomain.com/.well-known/apple-developer-merchantid-domain-association

  3. Verification Completion:

    • Ensure A-grade SSL Labs security rating
    • Click Verify button in Apple Developer console
    • Confirm successful verification status

Onerway Proxy Mode Setup ​

Use Case Recommendations

Recommended for Proxy Mode:

  • ✅ First-time Merchants: New to Apple Pay integration, seeking simplified setup
  • ✅ Rapid Deployment: Need quick deployment with simpler certificate management
  • ✅ Multi-domain Merchants: Managing multiple domains, prefer unified certificate infrastructure
  • ✅ No Apple Developer Account: Have not applied for or prefer not to manage Apple Developer accounts

Consider Merchant-Owned Account Mode:

  • 🔧 Full Control: Need complete control over merchant validation flows and certificate management
  • 🔧 Existing Infrastructure: Have established Apple Developer accounts and certificate management processes

1. Domain Infrastructure Requirements ​

SSL/TLS Setup ​

  • Protocol Support: TLS 1.2+ with modern cipher suites
  • Certificate Authority: Enterprise-grade certificates from recognized CAs
  • Security Rating: Minimum A-grade through SSL Labs

Domain Submission Process ​

  1. Domain Information Submission:

    • Provide complete domain URL to Onerway technical team
    • Format: https://your-store.com
    • Include any subdomains requiring Apple Pay integration

  2. Onerway Domain Registration:

    • Onerway registers domain within their Apple Developer infrastructure
    • Domain-specific verification file generation
    • Technical guidance provided for verification completion

2. Centralized Certificate Management ​

Onerway Certificate Infrastructure ​

  • Payment Processing Certificates: Unified certificates for secure transaction handling
  • Merchant Identity Certificates: Centralized validation workflow certificates
  • Automatic Maintenance: Automated certificate renewal and rotation

Verification File Deployment ​

  1. Receive Verification File:

    • Onerway provides apple-developer-merchantid-domain-association file

  2. File Deployment:

    bash
    # Deploy to designated server path:
https://your-store.com/.well-known/apple-developer-merchantid-domain-association

# Ensure proper MIME type and HTTPS accessibility
# Verify HTTPS accessibility returns HTTP 200 status
curl -I https://your-store.com/.well-known/apple-developer-merchantid-domain-association

  3. Verification Execution:

    • Onerway executes domain verification through Apple's infrastructure
    • Confirmation provided upon successful completion

Security Requirements ​

Server Infrastructure Requirements ​

SSL/TLS Setup Standards ​

  • Minimum TLS Version: TLS 1.2 (TLS 1.3 preferred)
  • Cipher Suites (in preference order):
    • ECDHE-RSA-AES128-GCM-SHA256
    • ECDHE-RSA-AES256-GCM-SHA384
    • ECDHE-ECDSA-AES128-GCM-SHA256
    • ECDHE-ECDSA-AES256-GCM-SHA384

Security Compliance Checklist ​

  • ✅ SSL Labs A-Grade: Achieve minimum A-grade security rating
  • ✅ Legacy Protocol Deprecation: Disable SSLv3, TLS 1.0, TLS 1.1
  • ✅ HSTS Implementation: Enable HTTP Strict Transport Security
  • ✅ SNI Support: Confirm Server Name Indication compatibility

Certificate Management Best Practices ​

Certificate Security ​

  • Secure Storage: Store certificates in secure, access-controlled locations
  • Regular Rotation: Implement automated certificate renewal processes
  • Monitoring: Monitor certificate expiration dates and validation status

Access Control ​

  • Principle of Least Privilege: Limit certificate access to essential personnel
  • Audit Logging: Maintain logs of certificate access and usage
  • Backup Procedures: Secure backup of critical certificates and keys

Verification & Testing ​

Setup Validation Checklist ​

Domain Verification ​

  • ✅ HTTPS Accessibility: Verification file returns HTTP 200 via HTTPS
  • ✅ SSL Rating: Domain achieves A-grade SSL Labs rating
  • ✅ DNS Resolution: Proper DNS configuration and resolution
  • ✅ Certificate Chain: Complete certificate chain validation

Common Setup Issues ​

Certificate Problems ​

  • Invalid Certificate Chain: Ensure complete certificate chain upload
  • Expired Certificates: Monitor and renew certificates before expiration
  • Incorrect CSR: Verify CSR generation follows Apple's specifications

Domain Verification Failures ​

  • HTTP Access: Verification file must be accessible via HTTPS only
  • Incorrect Path: File must be at exact .well-known path
  • SSL Rating: Domain must achieve minimum A-grade security rating
  • Firewall Restrictions: Ensure Apple's validation servers can access domain

Setup Completion Checklist ​

Merchant-Owned Account Mode Checklist ​

  • Created or confirmed Merchant ID in Apple Developer console
  • Requested and uploaded payment processing certificate from Onerway
  • (Optional) Configured Merchant Identity certificate (if building custom merchant validation)
  • Completed domain registration and verification file deployment
  • Verified domain through Apple Developer console

Onerway Proxy Mode Checklist ​

  • Submitted domain information to Onerway
  • Deployed Onerway-provided domain verification file
  • Confirmed domain SSL rating achieves A-grade
  • Received domain verification completion confirmation from Onerway

General Security Requirements Checklist ​

  • Enabled HTTPS with SSL Labs A-grade rating
  • Enabled HSTS and modern cipher suites
  • Domain verification file accessible via HTTPS

Next Steps ​

After completing the integration setup:

  1. Payment Flow Overview: Review the complete payment flow for end-to-end sequence diagrams
  2. Session Initialization: Configure Apple Pay session initialization
  3. Payment Flow Implementation: Implement the payment processing workflow
  4. Error Handling: Configure comprehensive error handling and troubleshooting