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

Configure the entitlement and provisioning for the app's bundle ID in Xcode and Apple Developer. Test reader preparation on a supported physical iPhone after initialization, merchant login, and active-location selection. Handle linking and preparation errors through the SDK; hardware support alone does not verify an entitlement. See Adding Tap to Pay and Running Payments.

Environment Configuration

UAT and Production Environments

Use the SDK's .uat environment with a UAT SDK client key for integration testing, and .production with the matching production key for live merchant payments. The published SDK also supports .custom(String) when Koard supplies a specific backend URL. It does not expose a .cert enum case.

Apple sandbox account setup and app entitlements are separate from Koard's backend environment selection. Use a dedicated test device and the Sandbox Apple Account guide for UAT Tap to Pay tests.

Environment Selection

To switch between environments, configure your SDK initialization:

let options = KoardOptions(
    environment: .uat,  // .production for live merchant payments
    loggingLevel: .debug
)

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

Check merchant linking status

Use GET /v1/accounts/{account_id}/linkstatus to read the merchant's current Apple Tap to Pay linking status. Supply the merchant's Koard account ID, rather than the processor's MID or an Apple ID. Your API key needs accounts:read and access to that merchant account. The merchant itself and its account ancestors can query it. A PSP account is not a valid target.

curl 'https://api.uat.koard.com/v1/accounts/YOUR_MERCHANT_ACCOUNT_ID/linkstatus' \
  -H 'X-Koard-apikey: YOUR_API_KEY'

The response is always an array, including when there is just one configured provider:

[
  {
    "account_id": "YOUR_MERCHANT_ACCOUNT_ID",
    "merchant_name": "Merchant Coffee Shop",
    "iso_name": "koard",
    "status": "LINKED",
    "linked": true,
    "created_date": null
  }
]
status linked Meaning
LINKED true Apple reports that the merchant is linked.
NOT_LINKED false Apple reports that the merchant is not linked.
DEACTIVATED false Apple reports that the merchant's link is deactivated.

merchant_name is the target merchant's name. iso_name identifies the configured PSP. Multiple entries are possible. The call reads current status and does not link, relink, or accept terms for the merchant.

An empty array means associated configurations exist but none has management credentials available for a lookup. It does not mean Apple returned NOT_LINKED. If there is no associated active configuration, the API returns 503. A missing or inaccessible merchant returns 404; a non-merchant target returns 400. Lookup failures return an error instead of a partial array or a fabricated status.

See the Accounts API reference for the response schema and error codes. This merchant linking status is separate from a PSP's Apple configuration and reporting inventory.

Sandbox Testing

Sandbox Tester Account Setup

If your SDK or API developers need to connect to Apple's sandbox through your UAT integration, 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 Creating a Sandbox Apple Account. It covers the account, the test iPhone, sandbox mode, and test cards in order.

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 UAT 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 UAT
  • All payment flows are tested with test cards
  • Production environment is properly configured before go-live

Support and Resources

Apple Documentation

Koard Resources