Where do I start?

The Yuno SDKs expose a single Transaction class. What changes between integrations is which parameters you pass and which controllers you override. Each decision is independent. Combine them freely. This page walks through the decisions you’ll make and points you to the relevant documentation for each. Flip the switch in each step and the code on the right assembles itself for your platform. Every block the code uses is also written under its step, so you can compose by hand: start from the base, then add the block of each step where you chose the non-default answer. A configuration block replaces the TransactionConfig, a payment-method block replaces the PaymentMethodSelected, a flag line goes inside TransactionConfig, and a controller block goes inside your controller class, or inside the transaction options on Web.

Base

The SDK does everything: it shows the form, creates the payment, handles 3DS and reports the result to onStatus. Create the checkout session with workflow: "SDK_SEAMLESS" for this base.

Base code

iOS
Android
Web

import SwiftUI
import SdkPayments

final class Checkout: SdkPayments.TransactionController {

    func start() {
        let paymentSelected = SdkPayments.PaymentMethodSelected(
            paymentMethodType: "CARD"
        )

        let config = SdkPayments.TransactionConfig(
            checkoutSession: "session-from-backend",
            countryCode: "US",
            language: "en",
            controller: self
        )

        SdkPayments.Transaction(config: config)
            .start(paymentSelected: paymentSelected)
    }

    func onStatus(status: SdkPayments.TransactionStatus) {
        print("Final status: \(status.status)")
    }
}

import com.yuno.payments.sdk.api.Transaction
import com.yuno.payments.sdk.api.TransactionConfig
import com.yuno.payments.sdk.api.TransactionController
import com.yuno.payments.sdk.api.models.PaymentMethodSelected
import com.yuno.payments.sdk.api.models.TransactionStatus

class CheckoutActivity : ComponentActivity(), TransactionController {

    private fun startCheckout() {
        val paymentSelected = PaymentMethodSelected(
            paymentMethodType = "CARD"
        )

        val config = TransactionConfig(
            checkoutSession = "session-from-backend",
            countryCode = "US",
            language = "en",
            controller = this
        )

        Transaction(config)
            .start(activity = this, paymentSelected = paymentSelected)
    }

    override fun onStatus(status: TransactionStatus) {
        println("Final status: ${status.status}")
    }
}

const transaction = sdkPayments.transaction({
    checkoutSession: 'session-from-backend',
    countryCode: 'US',
    language: 'en',
    elementSelector: '#payment-form',
    onStatus: (result) => {
        console.log('Final status:', result.status)
    },
})

const paymentMethod = { type: 'CARD' }

await transaction.start({ paymentMethod })

1. Are you processing a payment or saving a payment method?

This decision affects which session type you create on your backend and pass to the SDK.

To process a payment, create a checkout session and pass it to TransactionConfig as checkoutSession. Use this when you want to charge the customer.
To save a payment method without charging, create a customer session and pass it as customerSession. Use this when you want to enroll a card or other method for future use.
To pay and enroll at the same time, pass checkoutSession only:
- Cards. Enable the “save card on payment” flag in your Checkout Builder. The SDK charges the customer and stores the card for future use.
- Other payment methods. Make sure the enrollable variant of the method is added in your connections. When it is, the SDK handles payment and enrollment together based on the checkout session alone. On Web, also pass savePaymentMethodEnabled: true in TransactionConfig and create the checkout session with a customer_id. The SDK then adds a save option to the form.

You cannot pass checkoutSession and customerSession at the same time.See Sessions and Enrollment.

Use this configuration to enroll instead of charging

iOS
Android
Web

        let config = SdkPayments.TransactionConfig(
            customerSession: "session-from-backend",
            countryCode: "US",
            language: "en",
            controller: self
        )

        val config = TransactionConfig(
            customerSession = "session-from-backend",
            countryCode = "US",
            language = "en",
            controller = this
        )

const transaction = sdkPayments.transaction({
    customerSession: 'session-from-backend',
    countryCode: 'US',
    language: 'en',
    elementSelector: '#enrollment-form',
    onStatus: (result) => {
        console.log('Final status:', result.status)
    },
})

2. Who creates the payment?

This decision affects whether you override createPayment.

Default. The SDK creates the payment. After tokenization, the SDK calls Yuno to create the payment, handles 3DS if needed, and emits the final status to onStatus. You don’t override anything. Create the checkout session with workflow: "SDK_SEAMLESS" so the SDK can drive payment creation end-to-end. See the workflow field.
You create the payment. Override createPayment to receive the token. Send it to your backend, create the payment by calling POST /v1/payments, and resolve the Promise/Task. The SDK then queries the status and continues the flow.

workflow is a field on the POST /v1/checkout/sessions request body. It is not part of TransactionConfig and cannot be set from the SDK. It must match this decision:

SDK creates the payment (no override) → create the session with workflow: "SDK_SEAMLESS".
You create the payment (createPayment override) → use the default workflow (SDK_CHECKOUT).

With the default SDK_CHECKOUT and no createPayment override, the backend rejects the SDK’s payment creation and the transaction ends in INTERNAL_ERROR with message.source: "backend", so the flow cannot complete.

In an enrollment flow (when you pass customerSession), createPayment is not invoked with payment data. There is no payment to create. Overriding this controller has no effect for enrollment.

See createPayment.

Add this block to your controller when you create the payment

iOS
Android
Web

    func createPayment(token: [String: Any]) async throws {
        // Create the payment from your backend with POST /v1/payments, then return.
        try await myBackend.createPayment(token: token)
    }

    override suspend fun createPayment(token: Map<String, Any>) {
        // Create the payment from your backend with POST /v1/payments, then return.
        myBackend.createPayment(token)
    }

    createPayment: async (token) => {
        // Create the payment from your backend with POST /v1/payments, then resolve.
        await myBackend.createPayment(token.token)
    },

3. Who collects the payment data?

This decision affects whether you pass transactionData in PaymentMethodSelected.

Default. The SDK shows forms. The SDK presents the appropriate form (card form, APM data form, etc.) and collects input from the user.
You provide the data. Pass transactionData (data on Web) in PaymentMethodSelected with the values already collected (for example, card details captured by your own UI). The SDK skips the forms and tokenizes directly.

See PaymentMethodSelected and TransactionData.

Use this PaymentMethodSelected when you collected the data yourself

iOS
Android
Web

        let paymentSelected = SdkPayments.PaymentMethodSelected(
            paymentMethodType: "CARD",
            transactionData: SdkPayments.TransactionData(
                card: SdkPayments.CardTransactionData(
                    number: cardNumber,
                    securityCode: cvv,
                    expirationMonth: expMonth,
                    expirationYear: expYear,
                    holderName: holder
                )
            )
        )

        val paymentSelected = PaymentMethodSelected(
            paymentMethodType = "CARD",
            transactionData = TransactionData(
                card = CardData(
                    number = number,
                    securityCode = cvv,
                    expirationMonth = expMonth,
                    expirationYear = expYear,
                    holderName = holder
                )
            )
        )

const paymentMethod = {
    type: 'CARD',
    data: {
        card: {
            holderName: 'John Doe',
            number: '4111111111111111',
            securityCode: '123',
            expirationMonth: 12,
            expirationYear: 28,
        },
    },
}

4. Who controls the form’s UI? (iOS, Android)

This decision affects whether you override showView.

Default. The SDK presents the form full-screen. The SDK shows the form with its own header and submit button.
You embed the form. Override showView to receive the form view and a TransactionProcess control. Place the view in your own layout and call process.onSubmit() to control submission.

This controller is available on iOS and Android only.

On Web: your own pay button instead of `showView`

On Web the SDK renders the form inside the element you pass as elementSelector, so the form already sits in your layout. To use your own submit button, set showPayButton: false in TransactionConfig and call transaction.submit() from your button after start() has resolved. If the form is incomplete, submit() reports INTERNAL_ERROR with code FORM_INVALID through onStatus and keeps the form mounted. submit() is not available for enrollment transactions.See showView.

Add this block to your controller when you embed the form

iOS
Android

    func showView(view: AnyView?, process: SdkPayments.TransactionProcess, step: SdkPayments.TransactionViewStep) {
        // Place `view` in your own layout. Call process.onSubmit() from your own button.
    }

    override fun showView(view: Fragment, process: TransactionProcess, step: TransactionViewStep) {
        // Place the fragment in your own layout. Call process.onSubmit() from your own button.
    }

5. Who shows the loader?

This decision affects whether you override showLoading.

Default. The SDK shows its own loader during tokenization, payment creation, and status polling.
You show your own loader. Override showLoading to receive isLoading: true | false and render your own UI.

See showLoading.

Add this block to your controller when you show your own loader

iOS
Android
Web

    func showLoading(isLoading: Bool) {
        // Show or hide your own loader.
    }

    override fun showLoading(isLoading: Boolean) {
        // Show or hide your own loader.
    }

    showLoading: (isLoading) => mySpinner.toggle(isLoading),

6. Should the SDK show a result screen after the transaction?

This decision is controlled by a flag in TransactionConfig, not by overriding a controller.

Default. The SDK does not show a result screen. The transaction finishes silently and you receive the final status through onStatus.
The SDK shows a result screen. Set showStatusScreen: true in TransactionConfig and the SDK will present its built-in success/failure screen after the transaction finishes.

On Web the default is reversed. The SDK shows its result screen unless you set showStatusScreen: false in TransactionConfig.On iOS, put the flag after controller, as the last argument. Swift requires the arguments in the order the initializer declares them.onStatus is always called when the transaction finishes, regardless of this flag. It’s the controller you use to know the final result and react accordingly.See TransactionConfig and onStatus.

Add this line to TransactionConfig to show the SDK's result screen

iOS
Android
Web

            showStatusScreen: true

            showStatusScreen = true,

    showStatusScreen: true,

Always implement `onStatus`

Regardless of which decisions you make above, you should always implement onStatus. It’s the only way to know whether the transaction succeeded, failed, was rejected, or ended in any other final state. You’ll typically use that information to navigate, refresh data, or update your own UI.onStatus is invoked when the SDK has finished all its work (tokenization, payment creation, 3DS, status polling).On iOS, asynchronous methods such as PIX or boleto also report PENDING before the final status. Treat PENDING as not final. See onStatus.On Web, onStatus can report more than once on one transaction. A submit with an incomplete form reports INTERNAL_ERROR with code FORM_INVALID and keeps the form mounted. A declined card can be retried in place, and the retry reports its own status.See onStatus and Status.

Quick reference

Decision	Default	To change it	Read
Session type		Pass `checkoutSession` or `customerSession`	Enrollment
Who creates the payment	SDK	Override `createPayment`	`createPayment`
Who collects the data	SDK shows forms	Pass `transactionData`	`TransactionData`
Who renders the form UI (iOS, Android)	SDK presents full-screen	Override `showView`	`showView`
Who shows the loader	SDK shows its own loader	Override `showLoading`	`showLoading`
Show SDK’s result screen?	No (Web: Yes)	Set `showStatusScreen: true` in `TransactionConfig` (Web: `showStatusScreen: false` to hide it)	`TransactionConfig`

Next steps

Get Started. Install the SDK and run your first transaction.
Configuration. Full reference for TransactionConfig, PaymentMethodSelected, and TransactionData.
Controllers. Full reference for each controller and what changes when you override it.

Start here

Guides

Listen and take over

API reference

Upgrade from older SDKs

Base

1. Are you processing a payment or saving a payment method?

2. Who creates the payment?

3. Who collects the payment data?

4. Who controls the form’s UI? (iOS, Android)

On Web: your own pay button instead of `showView`

5. Who shows the loader?

6. Should the SDK show a result screen after the transaction?

Always implement `onStatus`

Quick reference

Next steps

​Base

​1. Are you processing a payment or saving a payment method?

​2. Who creates the payment?

​3. Who collects the payment data?

​4. Who controls the form’s UI? (iOS, Android)

​On Web: your own pay button instead of showView

​5. Who shows the loader?

​6. Should the SDK show a result screen after the transaction?

​Always implement onStatus

​Quick reference

​Next steps

Base

1. Are you processing a payment or saving a payment method?

2. Who creates the payment?

3. Who collects the payment data?

4. Who controls the form’s UI? (iOS, Android)

On Web: your own pay button instead of `showView`

5. Who shows the loader?

6. Should the SDK show a result screen after the transaction?

Always implement `onStatus`

Quick reference

Next steps