Quickstart Guide

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

Or include via CDN:

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

2. Initialize and process payment

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

// Initialize SDK
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
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',
async yunoCreatePayment(oneTimeToken) {
    // Your backend calls: POST https://api-sandbox.y.uno/v1/payments
    // with { payment_method: { token: oneTimeToken }, checkout_session: ... }
    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();

3. Add HTML container and trigger payment

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

<script>
document.getElementById('pay-button').addEventListener('click', async () => {
    await yuno.startPayment();
});
</script>

See Test cards below.For a comprehensive overview of all Web SDK parameters, see Web SDK Common Reference.Complete Web guide →

1. Install

CocoaPods:

pod 'YunoSDK', '~> 2.11.1'

Swift Package Manager:

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

2. Initialize and implement delegate

import YunoSDK

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

// In your view controller - implement YunoPaymentDelegate
class PaymentViewController: UIViewController, YunoPaymentDelegate {
    
    // 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()
        displayPaymentMethods()
    }
    
    func displayPaymentMethods() async {
        // Get payment methods view
        let paymentView = 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 {
        case .succeeded:
            print("Payment succeeded!")
        case .fail:
            print("Payment failed")
        case .processing:
            print("Payment processing")
        default:
            break
        }
    }
}

// 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 →

1. Install

build.gradle:

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

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

2. Initialize and process payment

Initialize in Application:

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        Yuno.initialize(
            this,
            publicApiKey = "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 com.yuno.payments.Yuno

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 ->
                    when (state) {
                        "SUCCEEDED" -> println("Payment succeeded!")
                        "FAILED" -> println("Payment failed")
                        "PROCESSING" -> println("Payment processing")
                        "REJECT" -> println("Payment rejected")
                        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(
                            showStatusYuno = true,
                            callbackOTT = { token ->
                                token?.let { ott ->
                                    // 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 →

Handling a failed payment

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

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: Customer ID, amount, country
Returns: checkout_session ID (used in SDK)
Reference: Create checkout session API

Example request:

{
  "country": "US",
  "customer_payer": {
    "id": "customer-123"
  },
  "amount": {
    "currency": "USD",
    "value": "2500"
  }
}

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: One-time token (from SDK callback), checkout session
Returns: Payment status and sdk_action_required field
Reference: Create payment API

Example request:

{
  "payment_method": {
    "token": "one-time-token-from-sdk"
  },
  "checkout": {
    "session": "checkout-session-id"
  }
}

Important: If the API response has 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.

Secure Fields

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

Secure Fields Guide

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

External Native Modules

1. Install

2. Initialize and process payment

3. Add HTML container and trigger payment

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 trigger payment

​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 trigger payment

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