Quickstart Guide

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.

Welcome to the Yuno SDKs quickstart guide. This guide shows you how to easily implement Yuno’s full payment flow, its most straightforward solution with pre-built UI and automatic payment method display. Choose your platform and follow the steps to start processing your first payments with Yuno.

Web SDK integration
iOS
Android

1. Install

npm install @yuno-payments/sdk-web

To start the SDK download while the page loads, add a preload and preconnects to your HTML <head>. See Preload the SDK script.Or include via CDN:

<script src="https://sdk-web.y.uno/v1.11/main.js"></script>

2. Initialize and process payment

import { loadScript } from '@yuno-payments/sdk-web';

// Load the SDK script, then initialize it with your public API key
// (with the CDN script tag, skip the import and use window.Yuno in place of loadScript())
const Yuno = await loadScript();
const yuno = await Yuno.initialize('your-public-api-key');

// Create checkout session on your backend
// Your backend calls: POST https://api-sandbox.y.uno/v1/checkout/sessions
// Backend adds: account_id, merchant_order_id, payment_description (server-side)
const session = await fetch('/api/create-session', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
    customer_id: 'customer-123',
    amount: { currency: 'USD', value: 1000 },
    country: 'US'
})
}).then(r => r.json());

// Configure checkout
await yuno.startCheckout({
checkoutSession: session.checkout_session,
elementSelector: '#payment-form',
countryCode: 'US',
language: 'en',
async createPayment(oneTimeToken) {
    // Your backend calls: POST https://api-sandbox.y.uno/v1/payments
    // with header: X-Idempotency-Key
    // and body: { account_id, description, country, merchant_order_id, amount,
    //             checkout: { session }, payment_method: { token: oneTimeToken }, ... }
    const payment = await fetch('/api/process-payment', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        one_time_token: oneTimeToken,
        checkout_session: session.checkout_session
    })
    }).then(r => r.json());
    
    // Required for async payment methods (3DS, PIX, etc.)
    await yuno.continuePayment();
}
});

// Mount payment form
await yuno.mountCheckout();

// Start the payment when the shopper clicks your pay button
document.getElementById('pay-button')?.addEventListener('click', async () => {
    await yuno.startPayment();
});

3. Add HTML container and pay button

<div id="payment-form"></div>
<button id="pay-button">Pay Now</button>

See Test cards below.For a comprehensive overview of all Web SDK parameters, see Web SDK Common Reference.Complete Web guide →New SDK equivalent: Web Full mode migration.

1. Install

CocoaPods:

pod 'YunoSDK', '~> 2.29.0'

Swift Package Manager:

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

2. Initialize and implement delegate

import UIKit
import YunoSDK

// Initialize in AppDelegate or App struct
Yuno.initialize(
    apiKey: "your-public-api-key",
    config: YunoConfig()
)

// In your view controller - implement YunoPaymentFullDelegate
class PaymentViewController: UIViewController, @preconcurrency YunoPaymentFullDelegate {

    // Required delegate properties
    var checkoutSession: String { "session-from-backend" }
    var countryCode: String { "US" }
    var language: String? { "en" }
    var viewController: UIViewController? { self }

    override func viewDidLoad() {
        super.viewDidLoad()
        Task { await displayPaymentMethods() }
    }

    func displayPaymentMethods() async {
        // Get payment methods view
        let paymentView: UIView = await Yuno.getPaymentMethodViewAsync(delegate: self)
        view.addSubview(paymentView)
        // Add constraints...
    }

    // Required: Create payment with one-time token
    func yunoCreatePayment(with token: String) {
        // Call your backend: POST /v1/payments
        createPaymentOnBackend(token: token) { result in
            // After payment creation, continue for async methods
            Yuno.continuePayment()
        }
    }

    // Required: Handle payment result
    func yunoPaymentResult(_ result: Yuno.Result) {
        switch result.status {
        case .succeeded:
            print("Payment succeeded!")
        case .fail:
            print("Payment failed")
        case .processing:
            print("Payment processing")
        default:
            break
        }
    }

    // Required by YunoPaymentFullDelegate
    func yunoDidSelect(paymentMethod: PaymentMethodSelected) {
        // Enable your pay button
    }

    func yunoDidUnenrollSuccessfully(_ success: Bool) {}

    func yunoUpdatePaymentMethodsViewHeight(_ height: CGFloat) {
        // Update your payment view height constraint
    }

    // Start payment when user taps pay button
    @IBAction func payButtonTapped(_ sender: UIButton) {
        Yuno.startPayment(showPaymentStatus: true)
    }
}

See Test cards below.For a comprehensive overview of all iOS SDK parameters, see iOS SDK Common Reference.Complete iOS guide →New SDK equivalent: iOS Full mode migration.

1. Install

build.gradle:

repositories {
    maven { url "https://yunopayments.jfrog.io/artifactory/snapshots-libs-release" }
}

dependencies {
    implementation 'com.yuno.payments:android-sdk:2.27.0'
}

2. Initialize and process payment

Initialize in Application:

import android.app.Application
import com.yuno.sdk.Yuno
import com.yuno.sdk.YunoConfig

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        Yuno.initialize(
            this,
            apiKey = "your-public-api-key",
            config = YunoConfig(
                keepLoader = true,
            )
        )
    }
}

For a detailed explanation of the keepLoader parameter and mandatory error handling, see the Android Reference Guide.

In Activity/Fragment:

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.rememberScrollState
import androidx.compose.foundation.verticalScroll
import androidx.compose.material3.Button
import androidx.compose.material3.Text
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import androidx.compose.ui.Modifier
import androidx.lifecycle.lifecycleScope
import com.yuno.presentation.core.components.PaymentMethodListViewComponent
import com.yuno.sdk.payments.continuePayment
import com.yuno.sdk.payments.startCheckout
import com.yuno.sdk.payments.startPayment
import kotlinx.coroutines.launch

class PaymentActivity : ComponentActivity() {
    private var checkoutSession: String? = null

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
    
        // Create checkout session on your backend first
        // Your backend calls: POST https://api-sandbox.y.uno/v1/checkout/sessions
        lifecycleScope.launch {
            val session = createCheckoutSession() // Your backend call
            checkoutSession = session.id
        
            // Start checkout with session
            startCheckout(
                checkoutSession = session.id,
                countryCode = "US",
                callbackPaymentState = { state, subState, message ->
                    when (state) {
                        "SUCCEEDED" -> println("Payment succeeded!")
                        "FAIL" -> println("Payment failed: ${message?.code}")
                        "PROCESSING" -> println("Payment processing")
                        "REJECT" -> println("Payment rejected: ${message?.reason}")
                        else -> println("Payment state: $state")
                    }
                }
            )
        }
    
        setContent {
            var paymentMethodSelected by remember { mutableStateOf(false) }
        
            Column(
                modifier = Modifier
                    .fillMaxSize()
                    .verticalScroll(rememberScrollState())
            ) {
                // Display payment methods
                PaymentMethodListViewComponent(
                    activity = this@PaymentActivity,
                    onPaymentSelected = { isSelected, _ ->
                        paymentMethodSelected = isSelected
                    }
                )
            
                // Pay button
                Button(
                    onClick = {
                        startPayment(
                            showPaymentStatus = true,
                            callbackOTT = { token ->
                                token?.let { ott ->
                                    lifecycleScope.launch {
                                        // Call your backend: POST /v1/payments
                                        // with { payment_method: { token: ott }, checkout_session: ... }
                                        createPayment(ott, checkoutSession!!)
                                    
                                        // Required for async payment methods
                                        continuePayment()
                                    }
                                }
                            }
                        )
                    },
                    enabled = paymentMethodSelected
                ) {
                    Text("Pay Now")
                }
            }
        }
    }
}

See Test cards below.For a comprehensive overview of all Android SDK parameters, see Android SDK Common Reference.Complete Android guide →New SDK equivalent: Android Full mode migration.

Handling a failed payment

New SDK equivalent: the onStatus controller. The Web SDK can recover from a failed payment without reloading the page. Two mechanisms work together:

Payment retry — inline card retry when the payment returns DECLINED or ERROR. In Seamless the SDK handles retry automatically. In Full Checkout, Lite, and Secure Fields you call continuePayment after your backend confirms the decline. Works for non-enrolled credit and debit cards. See Payment retry for the full reference.
Switching payment methods — call updateCheckoutSession(newSession) to inject a fresh checkout session without unmounting the SDK. Picking from the already-rendered payment-method list after a session swap works; a different set of payment methods requires unmounting and re-mounting the SDK — not a page reload. See updateCheckoutSession.

// Inside your createPayment callback:
const payment = await createPaymentOnYourBackend(oneTimeToken);

const isCard = payment.payment_method?.type === 'CARD';
const failed = payment.status === 'DECLINED' || payment.status === 'ERROR';

if (isCard && failed) {
  // Card retry: keeps the card form open with the decline shown.
  await yuno.continuePayment();
} else if (payment.checkout?.sdk_action_required) {
  // Additional action: 3DS, bank redirect, etc.
  await yuno.continuePayment({ showPaymentStatus: true });
} else {
  // No further SDK action — unmount.
  await yuno.unmountSdk();
}

On a retried attempt the SDK does not fire paymentResult. It delivers the cloned checkout session to your onLoading callback as { type: 'PAYMENT_RETRY', data: { newCheckoutSession } }. Register onLoading in your startCheckout configuration to receive it:

await yuno.startCheckout({
  checkoutSession: session.checkout_session,
  // ...
  onLoading: ({ type, data }) => {
    if (type === 'PAYMENT_RETRY') {
      // A fresh session has been cloned for the retry.
      const newCheckoutSession = data.newCheckoutSession;
    }
  }
});

Backend integration

Your backend must implement two API endpoints to work with Yuno. The new SDK uses the same checkout session: see Create the checkout session.

1. Create checkout session

Before displaying the payment UI, your backend creates a checkout session:

Endpoint: POST https://api-sandbox.y.uno/v1/checkout/sessions
Required (OpenAPI): account_id, merchant_order_id, payment_description, country
Also send: customer_id (from Create Customer) and amount { currency, value }
Optional for SDK: workflow (SDK_CHECKOUT | SDK_SEAMLESS | CHECKOUT), callback_url, checkout_id
Returns: checkout_session ID (used in SDK)
Reference: Create checkout session API

Example request:

{
  "account_id": "YOUR_ACCOUNT_ID",
  "merchant_order_id": "order-001",
  "payment_description": "Sandbox quickstart payment",
  "country": "US",
  "customer_id": "YOUR_CUSTOMER_UUID",
  "amount": {
    "currency": "USD",
    "value": 100
  },
  "workflow": "SDK_CHECKOUT"
}

2. Create payment

In the One-Time Token (OTT) callback, your backend creates the payment:

Endpoint: POST https://api-sandbox.y.uno/v1/payments
Required header: X-Idempotency-Key (unique UUID per attempt) — see Authentication
Required body (OpenAPI): account_id, description, country, merchant_order_id, amount, payment_method, checkout
payment_method.token = one-time token from the SDK callback
checkout.session = checkout session id from step 1
Returns: Payment status and sdk_action_required field
Reference: Create payment API

Example headers:

public-api-key: YOUR_PUBLIC_API_KEY
private-secret-key: YOUR_PRIVATE_SECRET_KEY
X-Idempotency-Key: YOUR_UUID
content-type: application/json
accept: application/json

Example request:

{
  "account_id": "YOUR_ACCOUNT_ID",
  "description": "Sandbox quickstart payment",
  "country": "US",
  "merchant_order_id": "order-001",
  "amount": {
    "currency": "USD",
    "value": 100
  },
  "customer_payer": {
    "id": "YOUR_CUSTOMER_UUID"
  },
  "checkout": {
    "session": "YOUR_CHECKOUT_SESSION_UUID"
  },
  "payment_method": {
    "token": "ONE_TIME_TOKEN_FROM_SDK"
  }
}

Important: If the API response has sdk_action_required: true or checkout.sdk_action_required: true, you must call the SDK’s continuePayment() method to complete async payment methods (3DS authentication, PIX, bank redirects, etc.).

Parameters

Primary parameters used in this quickstart:

Parameter	Description
`publicKey` / `apiKey`	Your Yuno public API key (frontend). From Yuno Dashboard → Developers > Credentials.
`checkoutSession`	Checkout session ID returned by your backend (create session endpoint). Required to start payment.
`countryCode`	ISO country code for the payment (for example, `US`, `CO`). See Country coverage.
`elementSelector` (Web)	CSS selector for the element where the payment form is mounted (e.g. `#payment-form`).

Full parameter reference: Payment flows (Web), Payment flows (iOS), Payment flows (Android).

Alternative integration methods

If you need more control over the user interface or specific payment flows, Yuno provides alternative integration methods:

Lite SDK

A lightweight integration that gives you full control over the payment method display while Yuno handles the secure payment processing.

Web Implementation
Android Implementation
iOS Implementation
New SDK equivalent: Web Lite mode migration

Secure Fields

Build your own payment forms from scratch using Yuno’s UI components for maximum customization (Web Only).

Secure Fields Guide
New SDK equivalent: Secure Fields

Test cards

The new SDK has its own list: see Test cards.

Card Number	Scenario
4111 1111 1111 1111	Success
4000 0000 0000 0002	Declined
4000 0000 0000 3220	3DS Challenge

Overview

Seamless SDK

Lite SDK

Headless SDK

Card Enrollment

Additional Features

Resources

Additional Platforms

Web Frameworks

Validate your integration

External Native Modules

1. Install

2. Initialize and process payment

3. Add HTML container and pay button

1. Install

2. Initialize and implement delegate

1. Install

2. Initialize and process payment

Handling a failed payment

Backend integration

1. Create checkout session

2. Create payment

Parameters

Alternative integration methods

Lite SDK

Secure Fields

Test cards

​1. Install

​2. Initialize and process payment

​3. Add HTML container and pay button

​1. Install

​2. Initialize and implement delegate

​1. Install

​2. Initialize and process payment

​Handling a failed payment

​Backend integration

​1. Create checkout session

​2. Create payment

​Parameters

​Alternative integration methods

​Lite SDK

​Secure Fields

​Test cards

1. Install

2. Initialize and process payment

3. Add HTML container and pay button

1. Install

2. Initialize and implement delegate

1. Install

2. Initialize and process payment

Handling a failed payment

Backend integration

1. Create checkout session

2. Create payment

Parameters

Alternative integration methods

Lite SDK

Secure Fields

Test cards