Going to Production on iOS

A working Koard integration in UAT is half of going live on iPhone. The other half is Apple's approval, which you run directly with Apple and which has two separate reviews. Plan for it in the first week of design: teams that reach this stage without a plan commonly lose two to six weeks going back and forth with Apple.

Complete the UAT checks in sections 1 and 2 of the Launch Checklist before you start. Then work through this page in order.

Use your own Apple Developer account. Apple grants both entitlements to the account that owns your app. Only the Account Holder can submit the requests and see Apple's replies, so involve that person early. Where Apple's form asks for your payment service provider, enter Koard. Your merchants do not need an entitlement. It belongs to your app, and each merchant only accepts Apple's terms inside it.

With a complete build, an app can go from development to live in one to two weeks. Most delays come from repeating the Tap to Pay review.

1. Tap to Pay Review: Process and Guidelines

Apple's Tap to Pay team reviews your app when you ask for the distribution entitlement in section 3. The team checks your in-app experience against Apple's Tap to Pay on iPhone review checklist, using three videos that you record. This review comes before App Store review and is separate from it.

Apple's development entitlement email links to two documents: its App Requirements and Review guide, and its App Review Requirements Checklist. Read both before you design screens, and fill in the checklist as you build, including its header. Apple returns a checklist with an empty header.

Apple will also look at your screens before you submit. Reply on your entitlement email thread and ask for feedback on your Tap to Pay on iPhone experience.

The four rejection reasons Koard sees most often are all in this review:

1. The videos do not show how a merchant accepts Apple's Terms and Conditions or links the merchant account.
2. The app has no in-app merchant education, because the developer planned to train merchants in person.
3. The reader is not prepared ahead of time, so the first tap in front of a customer is slow.
4. Button copy mixes "Tap to Pay" with "Tap to Pay on iPhone".

Choose Your Distribution Path First

Apple's requirements depend on how your app reaches merchants. Decide this before you design any screens.

What Apple Inspects

Apple inspects four moments in your app.

Prepare the Reader Before Checkout

Call KoardMerchantSDK.shared.prepare() after initialization, merchant login, and active-location selection, before a customer needs to tap. Apple's requirements ask for this call as early as possible in the app. Preparation time depends on the device, network, and merchant profile. Show inline progress and keep payment controls disabled until the reader is ready.

When the app returns to the foreground, check readiness and avoid starting overlapping preparation tasks. Do not discard preparation errors with try?. An account that is not linked needs a visible terms-acceptance action that calls linkAccountAsync(), followed by preparation. Reader token errors and other failures need their own visible recovery path.

Apple's checklist also asks for a progress indicator while the reader is being configured. Read KoardMerchantSDK.shared.status and show a progress bar or a simple state: not ready, preparing, ready.

See Running Payments for the SDK calls and Apple Best Practices for a preparation coordinator.

Terms and Conditions: Two Paths

A merchant accepts Apple's Tap to Pay on iPhone Terms and Conditions in one of two ways.

A merchant accepts once. One admin accepts for every user and device of that merchant, so offer the action in onboarding and again in Settings.

Always read terms acceptance from Apple through the Koard SDK. Do not cache it in a local flag, because a local flag can fall out of sync with Apple's records.

Record the Three Videos

Apple asks for three walkthrough videos. The Tap to Pay on iPhone reader screen cannot be captured by screen recording, so film the device with a second phone. Show every step in order. Apple rejects videos that skip or cut a step. The new user video applies only if merchants can sign up inside your app.

A merchant accepts Apple's terms only once. To record terms acceptance again, create a new merchant and record with it.

2. App Store Review: Process and Guidelines

After the Tap to Pay team grants the distribution entitlement, the App Store team reviews the build you submit through App Store Connect. For Public, Unlisted, and Custom App distribution this is the standard App Review plus a check specific to Tap to Pay on iPhone. Read Apple's App Review Guidelines for payments before you submit.

Put these in your App Store Connect submission notes:

• A statement that the app uses the Tap to Pay on iPhone entitlement, and how: available to everyone, or behind a feature flag.
• A description of your use case, for example "a point of sale app for small merchants".
• A test account that works. Apple recommends one, and reports that most rejections come from test accounts that do not work. Check it on a freshly reset iPhone before you submit.
• A video walkthrough or a PDF that shows, step by step: enrolling in Tap to Pay on iPhone and accepting the terms, adding items and starting a payment, and a completed payment. Add high-fidelity wireframes of your checkout.
• A note about any region limit or feature flag that controls Tap to Pay on iPhone, for example "App is limited to the US. The test account works in this region."
• If Tap to Pay on iPhone is your only acceptance method, set UIRequiredDeviceCapabilities to include iphone-ipad-minimum-performance-a12 so incompatible devices cannot download the app.

Submit the production build, because Apple reviews the app your merchants will use. App Store review usually takes a day or two.

Tap to Pay on iPhone does not run on iPad, and a merchant who opens the app there never sees the terms prompt. What to do depends on the app:

• If Tap to Pay on iPhone is the only way your app takes payments, make the app iPhone only.
• If your app also runs on iPad, or takes payments another way, keep it available there. Check KoardMerchantSDK.shared.isReaderSupported at runtime, offer Tap to Pay on iPhone only where it is true, and offer another acceptance method where it is not.

3. Request the Distribution Entitlement

Tap to Pay on iPhone has two entitlements. You already have the first one if you followed Setting Up the Entitlement.

To request it:

1. Confirm that your build meets every requirement in section 1 for your distribution path, and that the three videos show every step.
2. Have the Account Holder reply to the email from Apple's Wallet Entitlements team that granted the development entitlement. Keep the Case-ID line from that email in every message you send.
3. Apple answers with the materials it wants: the videos and a completed copy of its review checklist, and sometimes screen flows or screenshots. Apple gives you an upload link. After you upload, confirm that each file plays, then reply on the thread to say the files are there and that you are requesting the publishing entitlement. Apple reviews requests in the order it receives them. A video Apple cannot open stalls the review, and Apple may not tell you for days.
4. Wait for Apple's review. Allow about five business days. If Apple asks for changes, make them and answer on the same thread.

If you cannot find the original email, write to ttpoientitlements@apple.com, say that you did not receive it, and include your Apple Developer team ID.

If a review goes quiet for more than a week, tell support@koard.com. Koard can ask its Apple contacts what is holding it up.

Apple grants the entitlement for one app. An update to an approved app does not repeat the review. A different app on the same account does.

4. Use the Distribution Entitlement

Once Apple grants it, build the app you will ship.

4.1. Update Signing

Confirm that Tap to Pay on iPhone appears on your App ID, then create or regenerate a distribution provisioning profile so it includes the entitlement. Without the distribution entitlement, a distribution build fails with an error that the profile does not include com.apple.developer.proximity-reader.payment.acceptance. Setting Up the Entitlement shows where each setting lives.

4.2. Separate the Production Build

Keep UAT and production apart at build time so a UAT key can never ship.

1. In Xcode, select the project. Under PROJECT, Info, duplicate the Debug and Release configurations and name the copies Debug-Prod and Release-Prod.
2. Open Product, Scheme, Manage Schemes. Duplicate your scheme, name the copy for production, and assign the production configurations to each action, including Archive. Apple's Customizing the build schemes for a project covers the details.
3. Give each configuration its own Koard values, for example through .xcconfig files.

// Xcode .xcconfig: $() prevents // from starting a comment.
Koard-Dev.xcconfig
KOARD_API_BASE_URL = https:/$()/api.uat.koard.com
KOARD_API_KEY = ${KoardSandboxAPIKey}

Koard-Prod.xcconfig
KOARD_API_BASE_URL = https:/$()/api.koard.com
KOARD_API_KEY = ${KoardProductionAPIKey}

Keep credentials out of source control. Build settings and Info.plist values can be read from a shipped app, so the app must hold only its own app key. Backend API keys stay on your server.

4.3. Point the Build at Production

Initialize the SDK with the production environment and the production app key. Create that key in production with the payments:tap-ios permission, as described in Getting an API Key. Koard invites you to the production dashboard at app.koard.com once your agreement is in place. You create production keys there.

Production also needs its own merchant, terminal, location, and merchant credentials. Repeat merchant setup with production values, because nothing you created in UAT exists there. The terminal uses the merchant's production processor credentials, and the processor configuration ID is different from the UAT one.

struct KoardAppConfig {
    static let baseURL: URL = {
        guard let urlString = Bundle.main.object(forInfoDictionaryKey: "KOARD_API_BASE_URL") as? String,
              let url = URL(string: urlString) else {
            fatalError("Missing or invalid KOARD_API_BASE_URL")
        }
        return url
    }()

    static let apiKey: String = {
        guard let key = Bundle.main.object(forInfoDictionaryKey: "KOARD_API_KEY") as? String else {
            fatalError("Missing KOARD_API_KEY")
        }
        return key
    }()
}

#if KOARD_ENV_PRODUCTION
let environment: KoardEnvironment = .production
let loggingLevel: KoardLoggingLevel = .error
#else
let environment: KoardEnvironment = .uat
let loggingLevel: KoardLoggingLevel = .debug
#endif

let options = KoardOptions(
    environment: environment,
    loggingLevel: loggingLevel
)
KoardMerchantSDK.shared.initialize(options: options, apiKey: apiKey)

KoardOptions.environment accepts .uat, .production, or .custom(String). Lower loggingLevel for production builds, for example to .error or .none, so debug logs do not ship.

4.4. Verify on a Device

Use two iPhones if you can. Switching one phone between a Sandbox Apple Account and a normal one is the most common source of lost time.

• Keep the UAT build on the test iPhone that stays signed in with your Sandbox Apple Account.
• Install the production build on a separate iPhone signed in with a normal Apple Account, or reset the test iPhone first.
• In each environment, run a payment, a refund, a reversal, and a settlement check.
• In production, do not sign one iPhone in to more than two merchants within 24 hours. It causes problems with Apple. To test several setups, use one merchant with several locations.

4.5. Test the Build and Submit

1. Upload the production archive to App Store Connect.
2. Test that exact build through TestFlight, on a supported iPhone, with the production merchant.
3. Submit it for App Store review with the notes from section 2.

TestFlight works only with production: a normal Apple Account, the production app key, and a production merchant. A Sandbox Apple Account cannot take payments in a TestFlight build. Payments made in TestFlight are real and move money.

5. Apple Brand and Marketing Guidelines

Apple controls how Tap to Pay on iPhone is named and shown. These rules apply to your app's store listing, website, emails, and press, during launch and after it. Apple's Marketing Guidelines are the source, and Apple's version wins if this summary differs.

Getting the toolkit. The email in which Apple grants your entitlement links to the Marketing Guide and Toolkit for your region. It goes to the Account Holder of your Apple Developer Program membership, so ask that person to pass it to your marketing team. The Merchant Incentive Guide comes with it.

Checking your assets. Apple is specific about how these assets look. Koard works with Komplier for Apple marketing compliance. Its builder produces assets from Apple's templates, and its analyzer checks custom assets against Apple's rules before you publish them.

Design the in-app screens from Apple's Human Interface Guidelines for Tap to Pay on iPhone and the Tap to Pay on iPhone template in Apple Design Resources.

6. Merchant Support

You are the first line of support for your merchants. Apple expects help to be available inside the app, and merchants look there first. Koard takes the issues you cannot resolve: SDK behavior, Tap to Pay on iPhone behavior, certification, and infrastructure.

When a merchant reports a problem, start with iOS Troubleshooting. If you need Koard, send the details below to the right place.

Include the environment and the merchant, location, terminal, and transaction IDs when you write to Koard. Never send card numbers, PINs, API keys, or merchant credentials.

Common Rejection Reasons

Release

When App Store review passes, release the app. If you ship the build with Tap to Pay on iPhone behind a feature flag that you control, declare the flag in your App Store Connect notes and turn it on when you are ready.

After release, monitor payment outcomes, webhook delivery, and settlement, and keep a way to pause new payments if a problem appears.

Apple References

• Tap to Pay on iPhone for developers
• Entitlement request form
• Human Interface Guidelines: Tap to Pay on iPhone
• Marketing Guidelines
• ProximityReaderDiscovery
• App Review Guidelines

This page reflects Apple's App Review Checklist v1.5.1 (March 2025), Getting Started guide v1.2, and the Marketing Guidelines page as published in November 2026. Apple updates these documents. If you see a difference, Apple's version wins.

Next Step

Finish the remaining checks in the Launch Checklist, then release.