Troubleshooting

​

Enabling debug logs

​

On-screen log overlay (SwiftUI)

import SwiftUI
import Payrails

struct DebugView: View {
    var body: some View {
        Payrails.Debug.configViewer()
    }
}

​

Console logging

​

Installation issues

• Confirm the package URL is exactly https://github.com/payrails/ios-sdk.git.
• Click File → Packages → Reset Package Caches in Xcode, then resolve again.

• Swift Package Manager verifies the downloaded Payrails.xcframework.zip against the checksum in the package manifest, and the two disagree.
• Almost always a stale cache. Click File → Packages → Reset Package Caches, clear the Swift Package Manager cache at ~/Library/Caches/org.swift.swiftpm, then resolve again.
• Payrails never re-uploads a published zip, so a mismatch that survives a cleared cache is worth a support ticket with the SDK version.

• 3.0.0 replaces the source target with a binary target, and Package.resolved pins the revision that was resolved before the upgrade.
• Click File → Packages → Reset Package Caches, then File → Packages → Update to Latest Package Versions. Resolving again rewrites the pin.

• PayrailsCSE is linked statically into the framework binary, so this is not a missing-code problem. The generated .swiftinterface carries import PayrailsCSE, so the Swift compiler needs that module present to build against the binary. That holds even though no public Payrails API exposes a CSE type.
• Confirm the ios-cse package appears in the project’s resolved packages. If it is missing, resolve the Payrails package again. Its manifest declares both ios-cse and paypalcheckout-ios.
• The CSE code is therefore present twice: once absorbed into Payrails.framework, once as the separately resolved ios-cse package. Inside the framework that is 176 exported PayrailsCSE symbols, plus 626 from JOSESwift, which arrives transitively through ios-cse. That matters when you measure binary size or integrate PayrailsCSE directly. PayPalCheckout is the opposite case: it ships as a prebuilt binary XCFramework, so it stays a genuine external dynamic dependency.

• Each release is built with Xcode 16.4. Swift’s .swiftinterface format is not backward compatible across toolchains, so an older Xcode cannot read the module. Xcode 16.4 is the minimum, not a recommendation.
• Upgrade Xcode, or open a support ticket with the Xcode version.

​

SDK initialization issues

• The init payload data field is not valid base64-encoded JSON
• Ensure your backend passes the exact string returned by the Payrails POST /checkout/initialize endpoint without modification

• Payrails.createCardForm() or another factory was called before Payrails.createSession() completed
• These calls trigger a precondition failure if called without an active session — always await session creation first

• Check that your backend call succeeds in the production environment
• Verify that the env option matches your backend environment (.production vs .test)

​

Card form issues

• Ensure Payrails.createCardForm() is called before Payrails.createCardPaymentButton()
• The button holds a strong reference to the form at creation time; order matters

• Check that the card form has enough vertical space — error labels require height to render
• Use CardFormConfig(showRequiredAsterisk: true) to make required fields explicit

• Pass showCardIcon: true in CardFormConfig.
• Icons load from the asset catalog inside the framework bundle, which the package resolves automatically. If icons are missing after a clean resolve, open a support ticket with the SDK version.

• Your custom CardLayoutConfig is missing required fields (.CARD_NUMBER, .CVV, and at least one expiry field)
• All three are required for a valid submission

​

Apple Pay issues

• session.isApplePayAvailable is a device-capability check only (returns false when PKPaymentAuthorizationController.canMakePayments() is false). It does not inspect the merchant config.
• For a combined “configured and device capable” check, compose:
  let canShow = session.isApplePayAvailable
      && !session.getPaymentMethodConfig(.specific("apple_pay")).isEmpty
  
• The PKPaymentButton hides itself when PKPaymentAuthorizationViewController.canMakePayments() returns false.

• The merchant identifier in your app’s entitlements does not match the one in the Payrails merchant configuration
• Verify the capability is enabled under Signing & Capabilities in Xcode

• The init payload does not include an Apple Pay payment option configuration
• Contact your Payrails integration engineer to enable Apple Pay in your merchant account

​

PayPal issues

• Ensure the PayPalCheckout SDK is properly linked (check the build phases)
• The PayPal SDK requires a client ID in the init payload config; verify the payload includes it

• The user cancelled — onAuthorizeFailed(_:failure:) fires with failure.code == .userCancelled. In parallel, the SDK invokes the onSessionExpired closure supplied at createSession time to refresh the underlying execution; the merchant’s cached Session reference keeps working.

​

Payment issues

• onAuthorizeFailed(_ button:, failure:) carries an AuthorizationFailure struct. Switch on failure.code to give each case the right UX, and read failure.message / failure.rawError for detail:
  • .userCancelled — user dismissed the 3DS sheet. Show neutral copy, no error banner.
  • .authorizationError — authorization rejected (issuer decline, 3DS rejected, fraud blocked, etc.). failure.message is the backend’s errors[0].reason.result, falling back to “Authorization failed” when no detail is provided.
  • .authenticationError — session token rejected (HTTP 401 / 403). The SDK also fires its onSessionExpired refresh in the background.
  • .unknownError — network, SDK, or other unexpected failure. Inspect failure.rawError for the underlying error.

• Payrails executions are single-use. Once a payment terminates (success or failure), the same execution cannot be retried. Supply the onSessionExpired closure to Payrails.createSession(with:onSessionExpired:) so the SDK can mint a fresh execution in-place when needed; the merchant’s Session reference and cached buttons keep working unchanged.

• Confirm that payButton.presenter = self is set on the CardPaymentButton
• Confirm your view controller conforms to both PaymentPresenter and PayrailsCardPaymentFormDelegate if needed

• PayrailsError.finalStatusNotFoundAfterLongPoll — the payment status was not confirmed within the polling window
• This is typically a transient network or backend issue; prompt the user to check their payment status through your order history

​

Pre-authorization gate issues

​

Payments are blocked and no request reaches the backend

onRequestStart: { context, completion in
    guard context.paymentMethodCode == "payPal" else {
        completion(.proceed)   // ← omitting this blocks card, wallets, everything else
        return
    }
    myBackend.validate { completion($0) }
}

​

A payment is blocked roughly ten seconds after tapping

⚠️ onRequestStart did not answer within 10s for <method>; the payment was blocked.

​

Only PayPal or Apple Pay report a block without a reason

​

Stored instruments issues

• The init payload does not include any stored instruments for this holder reference
• Instruments with status other than "enabled" or "created" are filtered out

• Same as above — the list silently renders nothing when there are no eligible instruments
• Optionally check the count before adding the view: Payrails.getStoredInstruments().isEmpty

​

Crash report issues

• The SDK ships as a binary, so a crash reporter needs the SDK’s debug symbols to name those frames.
• Payrails builds Payrails.dSYMs.zip for every release. Request the file for the version you shipped through a support ticket, then upload it to your crash reporter alongside your app’s own dSYMs.
• Symbols only resolve for the SDK version in the build. dSYMs from another version do not match.

​

Getting help

1. Enable debug logs and capture the output
2. Reproduce the issue with env: .test to rule out production-only configuration issues
3. Check the PayrailsError.errorDescription for the specific failure reason
4. Open a support ticket with your executionId (from Payrails.query(.executionId)) and the full error description