DocsAPI Reference

Developing with Apple

Comprehensive guidelines and best practices for developing Tap to Pay on iPhone applications with Koard and Apple's payment technologies.

Overview

Developing Tap to Pay on iPhone applications requires careful attention to security, environment configuration, and compliance with Apple's requirements. This guide covers essential security measures, environment setup, and testing procedures to ensure a secure and compliant integration.

Security Considerations

Cardholder Data Protection

Given the sensitive nature of cardholder data processed through Tap to Pay on iPhone, Koard has implemented multiple security measures to ensure secure development and operation:

  • Secure SDK Architecture: All card data is handled securely through Apple's ProximityReader framework
  • Encrypted Communication: All API communications use industry-standard encryption
  • Tokenization: Sensitive payment data is tokenized and never stored in plain text
  • PCI DSS Compliance: Koard maintains PCI DSS Level 1 compliance standards

Entitlement Verification

Before initiating any Tap to Pay functionality, verify that your application has the correct Tap to Pay on iPhone entitlement.

Check Entitlement Status

You can verify the entitlement by accessing the readerIdentifier property. If the app is missing the required entitlement, readerIdentifier will throw a notAllowed error.

import ProximityReader

do {
    let readerIdentifier = try await ProximityReader.readerIdentifier
    // Entitlement is present and valid
} catch {
    // Handle notAllowed error if entitlement is missing
    print("Entitlement error: \(error)")
}

Important: Ensure your SDK returns an appropriate error if the entitlement is missing, and handle this error gracefully in your application.

Environment Configuration

Production and Certificate Environments

Koard provides two distinct environments for development and production use:

Certificate Environment (CERT)

The Certificate environment is designed for development and testing purposes. Use this environment when:

  • Developing internally with your team
  • Sharing builds with internal team members without a distribution certificate
  • Testing payment flows without processing real transactions
  • Conducting integration testing before production deployment

Best Practice: Always use the Certificate environment for internal development and testing. This ensures that test transactions remain isolated from production payment processing.

Production Environment

The Production environment is used for live merchant transactions. All devices connect to the Koard production environment by default when configured for production use.

Note: All customers working directly with Koard will have access to both environments via their API key configuration.

Environment Selection

To switch between environments, configure your SDK initialization:

let options = KoardOptions(
    environment: .cert,  // or .production
    loggingLevel: .debug
)

KoardMerchantSDK.shared.initialize(
    options: options,
    apiKey: "your-api-key"
)

Sandbox Testing

Sandbox Tester Account Setup

If your SDK or API developers need to connect to Apple's Certificate environment through your test environment, you must create a Sandbox Tester Account. This account allows you to test Tap to Pay functionality without processing real transactions.

Creating a Sandbox Tester Account

Follow these steps to create a sandbox tester account:

  1. Sign in to App Store Connect

    • Navigate to App Store Connect
    • Sign in with your Apple Developer account credentials

  2. Access Sandbox Testers

    • On the homepage, click Users and Access
    • In the top navigation, click Sandbox
    • Click the add button (+)
    • If this is your first time adding sandbox testers, click Create Test Accounts

  3. Complete Tester Information

    • Enter a first and last name for your tester
    • Enter an email address that:
      • Has not been used as an Apple Account
      • Has not been used to purchase iTunes or App Store content
      • Consider creating a dedicated email address for each sandbox tester
    • Enter a strong password that meets Apple's requirements
    • Choose an App Store country or region

  4. Email Subaddressing (Optional)

    If your email service provider supports email subaddressing with a plus sign (+), you can use subaddresses of a sandbox-specific address for multiple testers. For example:

    • Base email: billjames2@icloud.com
    • Subaddresses: billjames2+UK@icloud.com, billjames2+US@icloud.com, billjames2+JP@icloud.com

    All communications sent to the subaddresses are also sent to the base address.

  5. Invite the Tester

    • Review all information
    • Click Invite to complete the setup

  6. Configure Testing Devices

    • Sign out of your Apple Account on all testing devices
    • Sign back in with your new sandbox tester account

Important Notes:

  • Once you create a tester, you cannot edit the name, email, or password
  • Each test account is associated with one of 175 App Store storefronts
  • You can edit a tester's App Store country or region after creation to test on different storefronts using the same Sandbox account

Additional Resources

For more detailed information on creating sandbox tester accounts, see App Store Connect Help: Create a sandbox tester account.

Best Practices

Development Workflow

  1. Use Certificate Environment for all internal development and testing
  2. Verify Entitlements before attempting to use Tap to Pay functionality
  3. Implement Error Handling for missing entitlements and other error conditions
  4. Test Thoroughly using sandbox tester accounts before production deployment

Security Guidelines

  • Never log or store sensitive cardholder data
  • Implement proper error handling without exposing sensitive information
  • Use secure communication protocols (HTTPS/TLS)
  • Follow Apple's security guidelines for payment applications
  • Regularly update your SDK to the latest version for security patches

Testing Checklist

Before deploying to production, ensure:

  • Application has Tap to Pay on iPhone entitlement configured
  • Entitlement verification is implemented and tested
  • Error handling for missing entitlements is in place
  • Sandbox tester accounts are created and configured
  • Testing is performed in Certificate environment
  • All payment flows are tested with test cards
  • Production environment is properly configured before go-live

Support and Resources

Apple Documentation

Koard Resources