Skip to main content
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, 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

Requirements

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:
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.

full-checkout

Implement the Full iOS SDK: complete payment solution with automatic payment method display and minimal UI customization. See Requirements above.

Step 1: Include the library in your project

Follow the steps in Include the library in your project above.

Step 2: Initialize SDK with the public key

Retrieve your public API keys from the Yuno Dashboard. To start running the Yuno iOS Full checkout, import and initialize Yuno:
The Full checkout enables you to configure the appearance and process through the YunoConfig class. The available options are:

Options

Customization options:

Step 3: Create the checkout session

Each payment requires a new checkout_session. Use the Create checkout session 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 for details.

Checkout session options

Auth vs captureControl 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:
Swift 6 Concurrency RequirementsIf you’re using Swift 6, you’ll need to implement the YunoPaymentDelegate protocol with specific concurrency considerations. See the Swift 6 Concurrency guide for detailed implementation options and best practices.

Options

Important NoteUse 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. Card Data attributes The card_data dictionary contains the following attributes:

Step 5: Mount the SDK with automatic payment method display

Use getPaymentMethodViewAsync() to display all available payment methods automatically. Implement the YunoPaymentFullDelegate protocol:
Then call getPaymentMethodViewAsync() to retrieve the payment methods view:
The SDK returns the view type that matches the type annotation:
  • UIKit: Returns a UIView
  • SwiftUI: Returns a some View
ImportantAlways 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), 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. 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.
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 integrations, where you build your own payment method list. For how the render flow works, see Render mode.

Step 6: Start the payment process

After displaying the payment methods, call startPayment():

Options

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, create the payment using the Create payment endpoint. Use the checkout_session from Step 3 and the one-time token to create the payment.
In your backend, call the Create Payment endpoint:
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.
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, 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.
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)

Deep Links and Mercado Pago Checkout ProThis 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:
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:

Payment states

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.
* 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.