Additional resources
- Access the Release notes or the Yuno iOS SDK repository to verify the latest SDK version available.
Requirements
- CocoaPods or Swift Package Manager
- iOS 14.0 or above
- Active Yuno account; API credentials (obtain from the Yuno Dashboard → Developers > Credentials)
- Create
checkout_sessionand payment via the API; create a customer using the Create customer endpoint before creating a payment
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:YunoConfig class. The available options are:
Options
Customization options:Step 3: Create the checkout session
Each payment requires a newcheckout_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 theYunoPaymentDelegate 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
TheyunoCreatePayment(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
UsegetPaymentMethodViewAsync() to display all available payment methods automatically. Implement the YunoPaymentFullDelegate protocol:
getPaymentMethodViewAsync() to retrieve the payment methods view:
- 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.Step 6: Start the payment process
After displaying the payment methods, callstartPayment():
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 theyunoCreatePayment 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 thecheckout_session from Step 3 and the one-time token to create the payment.
sdk_action_required, which defines if additional actions are required to finish the payment based on the payment type.
Step 9: Continue payment
Yuno requires integrating the SDK’scontinuePayment 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.
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.
AppDelegate to pass the incoming URL to the Yuno SDK:
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 theyunoPaymentResult(_:) 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
PENDINGuntil PSP timeout or merchant cancellation - Important: The SDK will not return
rejectorprocessingin this scenario
Async payment methods (PIX, QR codes)
For asynchronous payment methods like PIX, when a user closes the QR window:- SDK Status: Returns
processing, optionally with a sub-status such asCLOSED_BY_USER - Backend Payment Status: Remains
PENDINGand the QR code remains valid until expiry - Checkout Session Reuse: Re-opening the same checkout session can display the same valid QR code
- No Automatic Cancellation: The PIX payment is not automatically cancelled when the user closes the QR window
Expired async payments
If a PIX QR code expires naturally:- Backend Status: Updated to
EXPIRED - SDK Status: SDK callbacks and polling endpoints return
EXPIREDconsistently