iOS Enrollment

This page documents a legacy SDK. Starting a new integration? Use the Yuno SDK. Already on a legacy SDK? Follow the migration guide.The new Yuno SDK (Web v2.x, iOS v3.x, Android v3.x) replaces the Full, Lite, Seamless, Render, Headless, and Secure Fields SDKs with one API across every platform. Legacy SDKs remain supported side by side during the transition and are scheduled for deprecation in 2027. Contact your Account Manager for migration planning.

The iOS SDK makes it easy to implement enrollment flows for saving payment methods to a customer account. Include the library in your project by following the same steps as in full-checkout.

Additional resources

See Choose the right integration for you if you’re unsure which flow to follow.
Access the Release notes or the Yuno iOS SDK repository to verify the latest SDK version available.
full-checkout Enrollment (iOS): Automatic enrollment with pre-built UI components

Requirements

CocoaPods or Swift Package Manager
iOS 14.0 or later
Active Yuno account; API credentials (obtain from the Yuno Dashboard → Developers > Credentials)
Create a customer using the Create customer endpoint before enrolling

Parameters

For the full list of parameters, see the iOS SDK Common Reference.

Parameter	Description
`customerSession`	Customer session ID from Create customer session API. Required.
`countryCode`	ISO country code (for example, `BR`). Required.
`language`	Language code for the UI. Optional.
`viewController`	UIViewController that presents the enrollment flow. Required for delegate.
`yunoEnrollmentResult(_:)`	Delegate: enrollment finished with result.
`YunoConfig` (initialize)	Optional: `appearance`, `saveCardEnabled`. See Common Reference.

full-checkout Enrollment (iOS)

The Yuno full-checkout iOS SDK provides enrollment with pre-built UI, card enrollment, status handling, and basic error management. See the preceding Requirements section.

Step 1: Create a customer and customer session

Create a customer in Yuno’s system using the Create customer endpoint before enrolling payment methods. This endpoint will return a customer_id that you’ll use to associate enrolled payment methods with the specific customer. Then create a customer session using the Create Customer Session endpoint. The session information will be used when calling the enrollment methods.

POST /v1/customer-session

{
  "country": "BR",
  "customer_id": "6c85a4e3-0a6c-423d-a12a-10045320ab4a"
}

The response includes a customer_session ID that you’ll use in the next step. On your server, also create an enrollment payment method object for that customer session to define which payment method the customer can enroll. Keep your private API keys on the server.

Step 2: Include the library in your project

Including the library in your project is done in the same way as in payment flows. Follow the steps in Include the library in your project there.

CocoaPods

pod 'YunoSDK', '~> 2.29.0'

Run:

pod install

Swift Package Manager

dependencies: [
    .package(url: "https://github.com/yuno-payments/yuno-sdk-ios.git", .upToNextMajor(from: "2.29.0"))
]

Check the Release notes or Yuno iOS SDK repository for the current SDK version.

Step 3: Initialize SDK with the public key

Initialize the SDK:

Get your Public API Key from the Yuno Dashboard
Initialize the SDK by calling Yuno.initialize() with your API key:

import YunoSDK

Yuno.initialize(
    apiKey: "PUBLIC_API_KEY",
    config: YunoConfig(),
    callback: { print("Yuno SDK initialized") }
)

Use the YunoConfig data class to customize the SDK’s behavior. Include this configuration when calling Yuno.initialize(). For example:

struct YunoConfig {
    var appearance: Appearance? = nil
    var saveCardEnabled: Bool = false
}

Step 4: Implement the enrollment delegate

Create a class that adopts the YunoEnrollmentDelegate protocol:

Swift 6 Concurrency RequirementsIf you’re using Swift 6, you’ll need to implement the YunoEnrollmentDelegate protocol with specific concurrency considerations. See the Swift 6 Concurrency guide for detailed implementation options and best practices.

protocol YunoEnrollmentDelegate: AnyObject {
    var customerSession: String { get }
    var countryCode: String { get }
    var language: String? { get }
    var viewController: UIViewController? { get }

    func yunoEnrollmentResult(_ result: Yuno.Result)
}

class ViewController: UIViewController, @preconcurrency YunoEnrollmentDelegate {
    var customerSession: String { "cus_ses_123456" }
    var countryCode: String { "BR" }
    var language: String? { "en" }
    var viewController: UIViewController? { self }

    func yunoEnrollmentResult(_ result: Yuno.Result) {
        switch result.status {
        case .succeeded:
            print("Enrollment successful")
        case .fail:
            print("Enrollment failed")
        case .processing:
            print("Enrollment processing")
        case .reject:
            print("Enrollment rejected")
        case .userCancelled:
            print("User canceled")
        case .internalError:
            print("Internal error")
        @unknown default:
            break
        }
    }
}

Options

Parameter	Description
`customerSession`	The unique identifier for the customer session.
`countryCode`	Country code where the enrollment is performed. See Country Coverage for supported countries.
`language`	Language code for the enrollment forms (for example, `"en"`, `"es"`, `"pt"`). See Supported languages.
`viewController`	The `UIViewController` used to present the enrollment flow. Required for proper UI presentation.
`yunoEnrollmentResult(_:)`	Called when the enrollment process completes with the final result.

Step 5: Start the enrollment process

Call the enrollPayment() method to display the enrollment flow:

func startEnrollment() {
    Yuno.enrollPayment(with: self, showPaymentStatus: true)
}

The SDK presents a full-screen UIViewController modally using the viewController provided in your delegate. In SwiftUI, wrap a UIViewController and return it via the viewController property.

Options

Parameter	Type	Description
`delegate`	`YunoEnrollmentDelegate`	The delegate object that handles enrollment callbacks.
`showPaymentStatus`	`Bool`	Whether to display status views during the enrollment process. When `true`, the SDK displays default status screens. When `false`, you handle status display through callbacks.

In SwiftUI, wrap a UIViewController and return it from the viewController property so the SDK can present the UI.

Step 6: Handle deep link return (Optional)

Only needed when the enrollment flow uses deep links. If your payment method does not use deep links, skip this step. Otherwise, handle the return in your AppDelegate:

func application(_ app: UIApplication,
                 open url: URL,
                 options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool {

    guard url.scheme == "yunoexample" else { return false }

    return Yuno.receiveDeeplink(url)
}

Make sure the url.scheme matches the callback_url used when creating the customer_session.

Step 7: Handle enrollment result

The SDK calls your yunoEnrollmentResult(_:) delegate method with the final status:

func yunoEnrollmentResult(_ result: Yuno.Result) {
    switch result.status {
    case .succeeded:
        print("Enrollment successful")
        // Navigate to success screen or update UI
    case .fail:
        print("Enrollment failed")
        // Show error message
    case .processing:
        print("Enrollment still processing")
        // Show processing message
    case .reject:
        print("Enrollment rejected")
        // Show rejection message
    case .userCancelled:
        print("User canceled")
        // Handle cancellation
    case .internalError:
        print("Internal error occurred")
        // Show error message
    @unknown default:
        break
    }
}

Enrollment Result States

State	Description	Action Required
`succeeded`	Enrollment completed successfully	No
`fail`	Enrollment failed due to validation or technical issues	Yes - Investigate and retry
`processing`	Enrollment in progress, awaiting approval	No
`reject`	Enrollment rejected (invalid data, fraud detection, etc.)	Yes - Inform user and suggest actions
`internalError`	Unexpected internal error occurred	Yes - Technical intervention required
`userCancelled`	User canceled the enrollment	No

Yuno.Result does not include tokens. Besides the high-level status, it exposes substatus and message (SDK 2.27.0 and later).

Complementary features

For styling, themes, form options, and additional configurations, see SDK customizations.

Common reference

For full parameter and customization details, see the iOS SDK Common Reference.

Overview

Seamless SDK

Lite SDK

Headless SDK

Card Enrollment

Additional Features

Resources

Additional Platforms

Web Frameworks

Validate your integration

External Native Modules

Additional resources

Requirements

Parameters

full-checkout Enrollment (iOS)

Step 1: Create a customer and customer session

Step 2: Include the library in your project

CocoaPods

Swift Package Manager

Step 3: Initialize SDK with the public key

Step 4: Implement the enrollment delegate

Options

Step 5: Start the enrollment process

Options

Step 6: Handle deep link return (Optional)

Step 7: Handle enrollment result

Enrollment Result States

Complementary features

Common reference

​Additional resources

​Requirements

​Parameters

​full-checkout Enrollment (iOS)

​Step 1: Create a customer and customer session

​Step 2: Include the library in your project

​CocoaPods

​Swift Package Manager

​Step 3: Initialize SDK with the public key

​Step 4: Implement the enrollment delegate

​Options

​Step 5: Start the enrollment process

​Options

​Step 6: Handle deep link return (Optional)

​Step 7: Handle enrollment result

​Enrollment Result States

​Complementary features

​Common reference

Additional resources

Requirements

Parameters

full-checkout Enrollment (iOS)

Step 1: Create a customer and customer session

Step 2: Include the library in your project

CocoaPods

Swift Package Manager

Step 3: Initialize SDK with the public key

Step 4: Implement the enrollment delegate

Options

Step 5: Start the enrollment process

Options

Step 6: Handle deep link return (Optional)

Step 7: Handle enrollment result

Enrollment Result States

Complementary features

Common reference