Troubleshooting

Use this guide with KoardSDK 1.0.21. Start with SDK Error Codes to identify the KoardMerchantSDKError case and any nested Tap to Pay error. For the complete checkout and response-handling implementation, see Running Payments.

Installation and Device Setup

If the app cannot import KoardSDK, verify that the Swift Package Manager product or XCFramework is linked to the app target. Follow Installing the SDK for the published dependency and supported Xcode version.

For .unsupportedPlatform(requiredVersion:), .TTPConfigurationFailed(.noReader), or persistent device-configuration errors:

1. Use a supported physical iPhone and OS. The package targets iOS 17+, while the documented Tap to Pay flow requires iOS 17.4+.
2. Verify the app's Tap to Pay entitlement and provisioning profile.
3. Enable a device passcode and configure the Apple Account needed for linking.
4. Confirm the API key, merchant credentials, and environment match.

Authentication and Active Location

For .unauthorized or .TTPConfigurationFailed(.notAuthenticated), log in before setting up the reader. If authentication keeps failing, verify credentials and merchant access. A .blockedAccount error requires Koard support.

For .missingLocationID, select a location with setActiveLocationID(...). For .missingTerminalID, verify that the selected location has a valid linked terminal. A Location and its terminal are separate configuration requirements. See Running Payments for location selection and validation.

Account Linking and Reader Preparation

If prepare() throws .accountNotLinked, show an explicit Link account action. When the merchant chooses it, call linkAccountAsync() in do/catch, then call prepare() after linking succeeds. Keep the linking action available if the merchant declines or the call fails.

Do not repeatedly invoke linking from an app-activation observer. The published SDK deliberately leaves linking under the merchant's control. If .TTPConfigurationFailed(.accountLinkingError(...)) persists, inspect the associated error and check the Apple Account, passcode, entitlement, and merchant configuration.

Invalid or Expired Reader Token

For .readerTokenInvalid(detail), check for a sandbox/production mismatch in the API key, merchant configuration, and app setup. The SDK clears its cached reader token for this failure, so a subsequent prepare() can obtain a fresh token. Retry preparation after checking configuration; contact support if the error persists.

This recovery prepares the reader. It does not retry a submitted payment. Do not print reader tokens, API keys, or merchant credentials in logs.

Cancellation and Card-Read Failures

Treat .TTPPaymentFailed(.canceled) as a canceled checkout. Let the customer choose whether to start again. For .paymentCardReaderError(...), inspect the associated reader/session error. For .noPaymentResult, .paymentCardReaderNilResult, or .invalidTransactionResponse, keep the checkout unresolved until you have checked any existing transaction.

Successful return from an SDK call does not establish approval. Inspect the returned transaction status, partial approval, and surcharge confirmation requirements using Running Payments.

Network, Rate Limits, and Uncertain Outcomes

• .network(...): restore connectivity. If a payment or follow-up was submitted, retrieve and reconcile the existing transaction before another attempt.
• .rateLimited(...): stop immediate retries and wait before another request. Do not turn a payment retry into an automatic loop.
• .server(...), .decodingFailure, or .unknown(...): retain the operation and transaction context. An unreadable response is not proof that the payment failed.
• .failedToConfirmSurcharge(...): inspect the associated error and retrieve the transaction to determine whether confirmation already completed.

See Payment Lifecycle for state-dependent follow-ups. Persist operation IDs for APIs that support them, as shown in Running Payments.

Before Contacting Support

Include the SDK and iOS versions, operation, environment, error case and nested case, redacted description, transaction/event ID when available, and steps that reproduce the problem. For associated native errors, include the error domain and code. Do not include API keys, credentials, reader tokens, or card data.

The SDK Error Codes page links to the published framework interface and release documentation used for this guide.