> ## Documentation Index
> Fetch the complete documentation index at: https://docs.y.uno/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Test in the sandbox first: base URL https://api-sandbox.y.uno (Test Mode in the Dashboard). Production is https://api.y.uno (Live Mode).
> Every API request needs the public-api-key and private-secret-key headers. Get them in the Dashboard at https://dashboard.y.uno/developers (Developers > Credentials); sandbox and production keys are different.
> Send an X-Idempotency-Key (a UUID) when creating payments, refunds and cancels, so retries do not create duplicates.
> Start with the Quickstart (https://docs.y.uno/docs/quickstart.md) and the agent guide (https://docs.y.uno/agents.md). To search these docs from a coding agent, connect the docs MCP server at https://docs.y.uno/mcp.

# iOS Payments

> Integrate full-checkout payment flows on iOS, from checkout session creation through payment result handling

> [!NOTE]
>
> **This page documents a legacy SDK.** Starting a new integration? Use the [Yuno SDK](https://docs.y.uno/docs/yuno-sdk/get-started.md). Already on a legacy SDK? Follow the [migration guide](https://docs.y.uno/docs/yuno-sdk/migration/overview.md).
>
> The new **Yuno SDK** (Web v2.x, iOS v3.x, Android v3.x, React Native v2.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 integrate payment flows into your iOS app.

## Additional resources

* Access the [Release notes](https://docs.y.uno/changelog/ios.md) or the [Yuno iOS SDK repository](https://github.com/yuno-payments/yuno-sdk-ios) to verify the latest SDK version available.

## Requirements

* [Swift Package Manager](https://www.swift.org/package-manager/)
* iOS 14.0 or above
* Active Yuno account; API credentials (obtain from the [Yuno Dashboard](https://dashboard.y.uno/) → **Developers** > **Credentials**)
* Create `checkout_session` and payment via the API; create a customer using the [Create customer endpoint](https://docs.y.uno/reference/customers/create-customer.md) before creating a payment

The first step is including the library in your project. YunoSDK is no longer published on CocoaPods; the last CocoaPods version is 2.30.0. Add the Yuno iOS SDK with Swift Package Manager:

```swift theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
dependencies: [
    .package(url: "https://github.com/yuno-payments/yuno-sdk-ios.git", .upToNextMajor(from: "2.31.0"))
]
```

Add `YunoSDK` (dynamic) or `YunoSDK-Static` (static, what CocoaPods shipped) to your app target, never both.

Once Step 1 is complete, continue with the full-checkout integration.

## Parameters

For the full list of parameters and YunoConfig, see the [iOS SDK Common Reference](https://docs.y.uno/docs/sdks/resources/references/ios.md).

| Parameter | Description |
| - | - |
| `checkoutSession` | Checkout session ID from your backend (Create checkout session API). Required. |
| `countryCode` | ISO country code (e.g. `BR`). Required. |
| `language` | Language code for the UI. Optional. |
| `viewController` | UIViewController that presents the payment flow. Required for delegate. |
| `yunoCreatePayment(with:)` | Delegate: create payment on your backend with the one-time token. |
| `yunoPaymentResult(_:)` | Delegate: payment finished. Receives `Yuno.Result` value (e.g., `.succeeded`, `.fail`, `.processing`). See [Payment Status reference](https://docs.y.uno/reference/getting-started/response-codes.md) for status mapping. |
| `YunoConfig` (initialize) | Optional: `appearance`, `saveCardEnabled`. See Common Reference. |

## full-checkout

Implement the Full iOS SDK: complete payment solution with automatic payment method display and minimal UI customization. See [Requirements](#requirements) above.

### Step 1: Include the library in your project

Follow the steps in [Include the library in your project](#include-the-library-in-your-project) above.

### Step 2: Initialize SDK with the public key

Retrieve your public API keys from the [Yuno Dashboard](https://dashboard.y.uno/).

To start running the Yuno iOS Full checkout, import and initialize Yuno:

```swift theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
import YunoSDK

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

The Full checkout enables you to configure the appearance and process through the `YunoConfig` class. The available options are:

```swift theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
struct YunoConfig {
    var appearance: Appearance? = nil
    var saveCardEnabled: Bool = false
}
```

#### Options

Customization options:

| customization option | Description |
| :- | :- |
| `appearance` | Enables SDK-wide UI customization. Use it to define global visual styles like colors, fonts, and button appearance. For more information, check the SDK customizations page. |
| `saveCardEnabled` | Enables the Save card checkbox on card flows. Check the Save card section for more information. |
| `language` | Defines the language to be used in the payment forms. You can set it to one of the available language options: `ar` (Arabic), `en` (English), `es` (Spanish), `pt` (Portuguese), `fil` (Filipino), `id` (Indonesian), `ms` (Malay), `th` (Thai), `zh-TW` (Chinese Traditional), `zh-CN` (Chinese Simplified), `vi` (Vietnamese), `fr` (French), `pl` (Polish), `it` (Italian), `de` (German), `ru` (Russian), `tr` (Turkish), `nl` (Dutch), `sv` (Swedish), `ko` (Korean), `ja` (Japanese), `hi` (Hindi), `bn` (Bengali), `ml` (Malayalam), `ur` (Urdu). |

### Step 3: Create the checkout session

Each payment requires a new `checkout_session`. Use the [Create checkout session](https://docs.y.uno/reference/checkout-sessions/create-checkout-session.md) endpoint to create one; use that session to initiate the payment.

If your payment flow sends users to an external browser (e.g., for 3DS authentication or bank redirects), set the `callback_url` when creating your checkout session. See [Handle external browser return](#step-6-handle-external-browser-return-optional) for details.

#### Checkout session options

| Parameter | Required | Description |
| - | - | - |
| `amount` | Yes | The primary transaction amount object containing `currency` (ISO 4217 code) and `value` (numeric amount). |
| `alternative_amount` | No | An alternative currency representation with the same structure as `amount`. Useful for multi-currency scenarios. |
| `callback_url` | Recommended | URL to redirect users back to your app after external browser flows (3DS, bank redirects). |
| `customer_id` | Yes | The customer ID obtained from the Create customer endpoint. |

> [!NOTE]
>
> **Auth vs capture**
>
> Control auth vs capture by sending `payment_method.detail.card.capture` in the checkout session: `false` = authorize only, `true` = capture immediately.

### Step 4: Implement the payment delegate

Create a class that adopts the `YunoPaymentDelegate` protocol:

> [!NOTE]
>
> **Swift 6 Concurrency Requirements**
>
> If you're using Swift 6, you'll need to implement the `YunoPaymentDelegate` protocol with specific concurrency considerations. See the [Swift 6 Concurrency](https://docs.y.uno/docs/sdks/resources/swift-6-concurrency.md) guide for detailed implementation options and best practices.

```swift theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
protocol YunoPaymentDelegate: AnyObject {
    var checkoutSession: String { get }
    var countryCode: String { get }
    var language: String? { get }
    var viewController: UIViewController? { get }

    func yunoCreatePayment(with token: String)
    func yunoCreatePayment(with token: String, information: [String: Any])
    func yunoPaymentResult(_ result: Yuno.Result)
}

class ViewController: UIViewController, @preconcurrency YunoPaymentDelegate {
    var checkoutSession: String { "438413b7-4921-41e4-b8f3-28a5a0141638" }
    var countryCode: String { "BR" }
    var language: String? { "en" }
    var viewController: UIViewController? { self }

    func yunoCreatePayment(with token: String) {
        // Create payment on your backend
    }

    func yunoCreatePayment(with token: String, information: [String: Any]) {
        // Create payment with additional information
    }

    func yunoPaymentResult(_ result: Yuno.Result) {
        // Handle payment result
    }
}
```

#### Options

| Parameter | Description |
| - | - |
| `checkoutSession` | The unique identifier for the checkout session. |
| `countryCode` | Country code where the payment is performed. See [Country Coverage](https://docs.y.uno/docs/sdks/resources/country-coverage.md) for supported countries. |
| `language` | Language code for the payment forms (e.g., `"en"`, `"es"`, `"pt"`). See [Supported languages](https://docs.y.uno/docs/sdks/resources/languages-supported.md). |
| `viewController` | The `UIViewController` used to present the payment flow. Required for proper UI presentation. |
| `yunoCreatePayment(with:)` | Called when a one-time token is generated. Create the payment on your backend. |
| `yunoCreatePayment(with:information:)` | Alternative callback that includes additional token information. Use only one version. See [OTT additional information](#ott-additional-information) for details. |
| `yunoPaymentResult(_:)` | Called when the payment process completes. Receives a `Yuno.Result` enum value. See [Payment Status reference](https://docs.y.uno/reference/getting-started/response-codes.md) for status mapping. |

> [!CAUTION]
>
> **Important Note**
>
> Use either `yunoCreatePayment(with:)` **OR** `yunoCreatePayment(with:information:)` based on your needs—not both. Calling both may cause issues.

#### OTT additional information

The `yunoCreatePayment(with:information:)` callback provides detailed information about the one-time token through the `information` dictionary. This is particularly useful for retrieving card-related data like the DPAN BIN.

| Key | Description |
| :- | :- |
| `token` | The one-time token (OTT). |
| `vaulted_token` | The vaulted token if applicable. |
| `vault_on_success` | Boolean indicating if the card should be vaulted on success. |
| `type` | Payment method type (e.g., `CARD`). |
| `card_data` | Dictionary containing card-related information. |

**Card Data attributes**

The `card_data` dictionary contains the following attributes:

| Attribute | Description |
| :- | :- |
| `iin` | The Issuer Identification Number (first 8 digits), also known as DPAN BIN for Apple Pay/Google Pay. |
| `lfd` | The last four digits of the card. |
| `brand` | Card brand (e.g., `VISA`, `MASTERCARD`). |
| `type` | Card type (e.g., `CREDIT`, `DEBIT`). |
| `issuer_name` | Name of the card issuer. |
| `country_code` | ISO country code of the issuer. |
| `category` | Card category (e.g., `CLASSIC`, `PLATINUM`). |

### Step 5: Mount the SDK with automatic payment method display

Use `getPaymentMethodViewAsync()` to display all available payment methods automatically. Implement the `YunoPaymentFullDelegate` protocol:

```swift theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
protocol YunoPaymentFullDelegate: YunoPaymentDelegate {
    func yunoDidSelect(paymentMethod: YunoSDK.PaymentMethodSelected)
    func yunoDidUnenrollSuccessfully(_ success: Bool)
    func yunoUpdatePaymentMethodsViewHeight(_ height: CGFloat)
}

class ViewController: UIViewController, @preconcurrency YunoPaymentFullDelegate {
    // ... YunoPaymentDelegate implementation ...

    func yunoDidSelect(paymentMethod: YunoSDK.PaymentMethodSelected) {
        print("Payment method selected: \(paymentMethod.paymentMethodType)")
    }

    func yunoDidUnenrollSuccessfully(_ success: Bool) {
        if success {
            print("Payment method removed successfully")
        }
    }

    func yunoUpdatePaymentMethodsViewHeight(_ height: CGFloat) {
        // Update container height if needed
    }
}
```

Then call `getPaymentMethodViewAsync()` to retrieve the payment methods view:

```swift theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
let paymentMethodsView: UIView = await Yuno.getPaymentMethodViewAsync(delegate: self)

// Add the view to your UI
// For UIKit:
view.addSubview(paymentMethodsView)

// For SwiftUI:
// Annotate the result as `some View` instead of `UIView`
```

The SDK returns the view type that matches the type annotation:

* **UIKit**: Returns a `UIView`
* **SwiftUI**: Returns a `some View`

> [!CAUTION]
>
> **Important**
>
> Always ensure the payment methods view container has proper constraints or layout configuration. The SDK will notify you of height changes through `yunoUpdatePaymentMethodsViewHeight(_:)` if needed.

#### Unfolded payment method list

When **Unfolded display** is enabled in the Checkout Builder ([Payment method list style](https://docs.y.uno/docs/using-yuno/dashboard-overview/checkout-builder.md#payment-method-list-style)), the form of the selected payment method opens inline, under its row in the list returned by `getPaymentMethodViewAsync()`, instead of on a separate screen. The SDK reads this setting from your checkout configuration, so no code change is needed to turn it on.

| SDK version | Inline form |
| :- | :- |
| Before 2.22.0 | Card only. Other payment methods open their form on a separate screen. |
| 2.22.0 and later | Card and alternative payment methods (for example PIX, PSE, or Boleto). |

Apple Pay, Click to Pay, and Revolut Pay keep their own payment sheet, and payment methods that don't collect data skip the form.

With the unfolded list, your pay button calls `startPayment()` for every payment method. The SDK validates the inline form, shows field errors in place if data is missing, and continues the flow (one-time token, redirects, and `continuePayment()`) once the form is valid.

> [!WARNING]
>
> Don't combine the Full payment method list with the render flow (`startPaymentRenderFlow`) to show the form of the payment method selected in that list. With unfolded display on, the form is already shown inline in the list, so the customer sees it twice. Use the render flow only in [Lite](https://docs.y.uno/docs/sdks/lite-ios/checkout.md) integrations, where you build your own payment method list. For how the render flow works, see [Render mode](https://docs.y.uno/docs/yuno-sdk/migration/ios/payment/render.md).

### Step 6: Start the payment process

After displaying the payment methods, call `startPayment()`:

```swift theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
Yuno.startPayment(showPaymentStatus: true)
```

#### Options

| Parameter | Description |
| :- | :- |
| `showPaymentStatus` | A boolean that specifies whether the payment status should be displayed within the Yuno interface. When `true`, the SDK displays default status screens. When `false`, you handle status display through callbacks. |

### Step 7: Get the one-time token (OTT)

After the customer fills out the requested data in Yuno's payment forms, you will obtain the one-time token, a required parameter to create a payment using the Yuno API.

The one-time token will be shared by Yuno using the `yunoCreatePayment` function you provided in Step 4 when implementing the delegate. The one-time token will be available in the callback.

A loader can be shown while the one-time token is generated. Use Yuno's default or implement your own with the required configuration.

### Step 8: Create the payment

After receiving the one-time token from [Step 7](#step-7-get-the-one-time-token-ott), create the payment using the [Create payment endpoint](https://docs.y.uno/reference/payments/create-payment.md). Use the `checkout_session` from [Step 3](#step-3-create-the-checkout-session) and the one-time token to create the payment.

```swift theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
func yunoCreatePayment(with token: String) {
    // Call your backend to create the payment
    createPaymentOnBackend(token: token) { result in
        switch result {
        case .success:
            // Payment created successfully
            // Call continuePayment() if needed
            Yuno.continuePayment()
        case .failure(let error):
            // Handle error
            print("Payment creation failed: \(error)")
        }
    }
}
```

In your backend, call the Create Payment endpoint:

```http theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
POST /v1/payments

{
  "payment_method": {
    "token": "9ee44ac7-9134-4598-ae28-a26fec03099d"
  },
  "checkout_session": "438413b7-4921-41e4-b8f3-28a5a0141638"
}
```

The response from the Create payment endpoint will include the parameter `sdk_action_required`, which defines if additional actions are required to finish the payment based on the payment type.

> [!WARNING]
>
> **Required:** Integrate the `continuePayment` method after the payment is created. Some asynchronous payment methods require additional customer actions. When the API response sets `sdk_action_required` to `true`, call `Yuno.continuePayment()` to display the necessary screens.

### Step 9: Continue payment

Yuno requires integrating the SDK's `continuePayment` method after the payment is created, as certain asynchronous payment methods require additional customer actions to complete. The response from the [Create payment endpoint](https://docs.y.uno/reference/payments/create-payment.md), from Step 8, will include an `sdk_action_required` field. If it returns `TRUE`, you need to call the `continuePayment()` function to show additional screens that allow the customer to complete the payment. Otherwise, this step is not necessary.

```swift theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
Yuno.continuePayment()
```

To show your payment status screens, handle status through the `yunoPaymentResult(_:)` delegate method instead of using the SDK's default status display.

### Step 10: Handle external browser return (Optional)

> [!CAUTION]
>
> **Deep Links and Mercado Pago Checkout Pro**
>
> This step is only required if you're using a payment method that relies on deep links or Mercado Pago Checkout Pro. If your payment methods don't use deep links, you can skip this step.

Some payment methods take users out of your app to complete the transaction. Once the payment is finished, the user is redirected back using a deep link. Update your `AppDelegate` to pass the incoming URL to the Yuno SDK:

```swift theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
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` you provided when creating the `checkout_session`.

### Step 11: Handle payment result

The SDK returns the payment result through the `yunoPaymentResult(_:)` delegate method:

```swift theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
func yunoPaymentResult(_ result: Yuno.Result) {
    switch result.status {
    case .succeeded:
        print("Payment succeeded")
        // Navigate to success screen
    case .fail:
        print("Payment failed")
        // Show error message
    case .processing:
        print("Payment is processing")
        // Show processing message
    case .reject:
        print("Payment was rejected")
        // Show rejection message
    case .userCancelled:
        print("User canceled payment")
        // Handle cancellation
    case .internalError:
        print("Internal error occurred")
        // Show error message
    @unknown default:
        break
    }
}
```

#### Payment states

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

#### Payment status validation

This section explains how the SDK handles payment status when users cancel or leave payment flows, and how the SDK status relates to the backend payment status in these scenarios.

##### Sync payment methods (Apple Pay)

For synchronous payment methods like Apple Pay, when a user cancels before PSP response:

* **SDK Status**: Returns `userCancelled` (CANCELLED\_BY\_USER)
* **Backend Payment Status**: Remains `PENDING` until PSP timeout or merchant cancellation
* **Important**: The SDK will not return `reject` or `processing` in this scenario

This ensures that the backend payment remains in a pending state and can be properly handled by the merchant's system.

##### Async payment methods (PIX, QR codes)

For asynchronous payment methods, when a user closes the payment window before completing the payment:

* **SDK Status**: Returns `userCancelled`\*.
* **Backend payment status**: Remains `PENDING` and the payment code remains valid until expiry.
* **Checkout session reuse**: Re-opening the same checkout session can display the same valid payment code.
* **No automatic cancellation**: The payment is not automatically cancelled on the backend when the user closes the window.
* **Confirming status**: `userCancelled` means the shopper left the screen, not that the payment failed. Confirm the final state via webhook or `GET /v1/payments/{payment_id}` before you show a cancellation.

> [!NOTE]
>
> \* Payment methods that show a payment code or voucher (PIX QR code, boleto, OXXO and similar), and Pix Parcelado, return `processing` with sub-status `CLOSED_BY_USER` instead of `userCancelled` when the user closes the screen. The payment stays `PENDING` on the backend and can still be completed.

##### Expired async payments

If a PIX QR code expires naturally:

* **Backend Status**: Updated to `EXPIRED`
* **SDK Status**: SDK callbacks and polling endpoints return `EXPIRED` consistently

This ensures merchants receive accurate status information when a payment method has expired

## Common reference

For full parameter and customization details, see the [iOS SDK Common Reference](https://docs.y.uno/docs/sdks/resources/references/ios.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.