iOS Integration Guidelines

For end‑to‑end context and field definitions, see Hosted Payment Page.

Integration Steps

On iOS, integrating the Hosted Payment Page involves four steps:

1. Initiating a payment request on your backend

2. Opening the Hosted Page in the device browser

3. Handling the redirect back into your app

4. Confirming the transaction status.

1. Initiate Payment Request

Your backend calls Codapay’s Payment/init API to create a transaction and uses the returned txnId to build the Hosted Page URL:

Sandbox

https://sandbox.codapayments.com/airtime/begin?browser_type=mobile-web&txn_id={txnId}

Production

https://airtime.codapayments.com/airtime/begin?browser_type=mobile-web&txn_id={txnId}

Return this URL to your app.

See Initiate Payment Request for full parameter list and examples

2. Display Hosted Payment Page

From your iOS app, open the Hosted Page URL in the system's default browser

if UIApplication.shared.canOpenURL(url) {
    UIApplication.shared.open(url, options: [:], completionHandler: nil)
}

See Display Hosted Page for URL formats and additional details

3. Redirect URLs

After payment success or failure, Codapay redirects the user to your configured Redirect URL. On iOS, you need to capture this redirect and return the user into your app session.

Two options are available:

• Universal Links (recommended) – Provide the smoothest user experience and better security.

• Custom URL Schemes (alternative) – Simpler to implement, but can be intercepted and are less reliable.

See how to set up Redirect URLs on Coda portal and configuration examples

Detailed iOS setup steps are available in the Implementation Details section below

4. Check Payment Status

Do not rely only on the redirect URL, since it can be forged. Always check the actual status with Codapay.

• Webhook notification (recommended): Codapay sends the final result to your backend.

• Inquiry API: If the webhook has not yet been received, your backend can query the transaction status.

Best practice:

1. Codapay sends webhook notification to your backend.

2. Browser redirects user back into the app (Universal Link or scheme).

3. App queries backend for the result.

4. Backend updates the user’s inventory or entitlements.

See Transaction Status Notifications and Check Payment Status in the general documentation for specifications and examples

Implementation Details

This section provides the step-by-step configuration needed to support redirects on iOS. Use this if you need the full Apple setup.

Universal Links (recommended)

1. Configure Associated Domains in your Apple Developer account:

   1. In Apple Developer, create or edit your App Identifier and enable Associated Domains.

   2. Note your Team ID and Bundle ID — together they form the App ID you will declare in the JSON file.

2. Create and host apple-app-site-association on your domain

   1. Define the file content using your App ID (Team ID + Bundle ID) and the URL paths you want to match (e.g., success, pending, failure). See an example below.

   2. Save the file exactly as apple-app-site-association

   3. Upload the file to https://<your-domain>/.well-known/apple-app-site-association

Example:

{
  "applinks": {
    "details": [
      {
        "appIDs": ["KV7GMR96XX.com.coda.outlinkdemo"],
        "components": [
          { "/": "/payments/success", "?", "*", "comment": "Match success redirect URL" },
          { "/": "/payments/pending", "?", "*", "comment": "Match pending redirect URL" }
        ]
      }
    ]
  }
}

1. Enable Associated Domains in Xcode: In Signing & Capabilities, add Associated Domains and register your domain with the applinks: prefix

2. Handle Universal Links in the app

AppDelegate (iOS ≤12)

import UIKit

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
    
    func application(_ application: UIApplication,
                     continue userActivity: NSUserActivity,
                     restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
        
        // Handle Universal Links
        guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
              let url = userActivity.webpageURL else { return false }
        
        handleUniversalLink(url)
        return true
    }
    
    private func handleUniversalLink(_ url: URL) {
        guard let components = URLComponents(url: url, resolvingAgainstBaseURL: false) else {
            print("❌ Failed to parse Universal Link URL")
            return
        }
        
        // Parse the URL to extract payment status
        if let status = components.queryItems?.first(where: { $0.name == "status" })?.value {
            handlePaymentStatus(status: status)
        } else if components.path.contains("success") {
            handlePaymentStatus(status: "success")
        } else if components.path.contains("failure") {
            handlePaymentStatus(status: "failure")
        }
    }
    
    private func handlePaymentStatus(_ status: String) {
        // Cross check with the backend
    }
}

SceneDelegate (iOS 13+)

import UIKit

class SceneDelegate: UIResponder, UIWindowSceneDelegate {
    
    var window: UIWindow?
    
    func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
        // Handle Universal Links
        guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
              let url = userActivity.webpageURL else { return }
        
        handleUniversalLink(url)
    }
    
    private func handleUniversalLink(_ url: URL) {
        guard let components = URLComponents(url: url, resolvingAgainstBaseURL: false) else {
            print("❌ Failed to parse Universal Link URL")
            return
        }
        
        // Parse the URL to extract payment status
        if let status = components.queryItems?.first(where: { $0.name == "status" })?.value {
            handlePaymentStatus(status: status)
        } else if components.path.contains("success") {
            handlePaymentStatus(status: "success")
        } else if components.path.contains("failure") {
            handlePaymentStatus(status: "failure")
        }
    }
    
    private func handlePaymentStatus(_ status: String) {
        // Cross check with the backend
    }
}

SwiftUI

import SwiftUI

@main
struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
                .onOpenURL { url in
                    // Handle Universal Links
                    handleUniversalLink(url)
                }
        }
    }
    
    private func handleUniversalLink(_ url: URL) {
        guard let components = URLComponents(url: url, resolvingAgainstBaseURL: false) else {
            print("❌ Failed to parse Universal Link URL")
            return
        }
        
        // Parse the URL to extract payment status
        if let status = components.queryItems?.first(where: { $0.name == "status" })?.value {
            handlePaymentStatus(status: status)
        } else if components.path.contains("success") {
            handlePaymentStatus(status: "success")
        } else if components.path.contains("failure") {
            handlePaymentStatus(status: "failure")
        }
    }
    
    private func handlePaymentStatus(_ status: String) {
        // Cross check with the backend
    }
}

Custom URL Schemes (alternative)

Use only when Universal Links cannot be used. Behaviour is undefined if multiple apps register the same scheme.

Universal Links are recommended for a smoother experience.

1. Register the scheme in Info.plist

Add your custom scheme under CFBundleURLTypes

Example:

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLName</key>
    <string>com.yourcompany.yourapp</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <!-- Make sure the scheme is unique -->
      <string>coda</string>
    </array>
    <key>CFBundleURLHosts</key>
    <array>
      <string>yourapp.yourcompany.com</string>
    </array>
  </dict>
</array>

1. Handle the scheme in the app

AppDelegate (iOS ≤12)

import UIKit

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
  func application(_ app: UIApplication,
                   open url: URL,
                   options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
    // Handle custom scheme URL
    handleCustomSchemeURL(url)
    return true
  }

  private func handleCustomSchemeURL(_ url: URL) {
    guard let components = URLComponents(url: url, resolvingAgainstBaseURL: false) else {
      print("❌ Failed to parse custom scheme URL")
      return
    }

    // Parse the URL to extract payment status
    if let status = components.queryItems?.first(where: { $0.name == "status" })?.value {
      handlePaymentStatus(status: status)
    }
  }

  private func handlePaymentStatus(_ status: String) {
    // Post notification for view controllers to handle
    let notificationName: Notification.Name
    switch status.lowercased() {
    case "success": notificationName = .paymentSuccess
    case "failure": notificationName = .paymentFailure
    default:
      print("⚠ Unknown payment status: \(status)")
      return
    }

    DispatchQueue.main.async {
      NotificationCenter.default.post(name: notificationName, object: nil)
    }
  }
}

extension Notification.Name {
  static let paymentSuccess = Notification.Name("PaymentSuccess")
  static let paymentFailure = Notification.Name("PaymentFailure")
}

SceneDelegate (iOS 13+)

import UIKit

class SceneDelegate: UIResponder, UIWindowSceneDelegate {
  var window: UIWindow?

  func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
    guard let urlContext = URLContexts.first else { return }
    let url = urlContext.url
    handleCustomSchemeURL(url)
  }

  private func handleCustomSchemeURL(_ url: URL) {
    guard let components = URLComponents(url: url, resolvingAgainstBaseURL: false) else {
      print("❌ Failed to parse custom scheme URL")
      return
    }

    if let status = components.queryItems?.first(where: { $0.name == "status" })?.value {
      handlePaymentStatus(status: status)
    }
  }

  private func handlePaymentStatus(_ status: String) {
    let notificationName: Notification.Name
    switch status.lowercased() {
    case "success": notificationName = .paymentSuccess
    case "failure": notificationName = .paymentFailure
    default:
      print("⚠ Unknown payment status: \(status)")
      return
    }

    DispatchQueue.main.async {
      NotificationCenter.default.post(name: notificationName, object: nil)
    }
  }
}

SwiftUI

import SwiftUI

@main
struct MyApp: App {
  var body: some Scene {
    WindowGroup {
      ContentView()
        .onOpenURL { url in
          handleCustomSchemeURL(url)
        }
    }
  }

  private func handleCustomSchemeURL(_ url: URL) {
    guard let components = URLComponents(url: url, resolvingAgainstBaseURL: false) else {
      print("❌ Failed to parse custom scheme URL")
      return
    }

    if let status = components.queryItems?.first(where: { $0.name == "status" })?.value {
      handlePaymentStatus(status: status)
    }
  }

  private func handlePaymentStatus(_ status: String) {
    let notificationName: Notification.Name
    switch status.lowercased() {
    case "success": notificationName = .paymentSuccess
    case "failure": notificationName = .paymentFailure
    default:
      print("⚠ Unknown payment status: \(status)")
      return
    }

    DispatchQueue.main.async {
      NotificationCenter.default.post(name: notificationName, object: nil)
    }
  }
}

Security Considerations

• Do not trust redirect URLs alone. They can be forged. Always cross-check payment status with your backend using webhook or inquiry

• Validate all incoming URLs. Ensure they come from your expected domain (for Universal Links) or your registered scheme (for custom URLs)

• Universal Links are safer than custom schemes. They verify domain ownership and prevent interception by other apps