Quickstart Guide

Welcome to the Yuno SDKs quickstart guide. This guide shows you how to easily implement our full payment flow, Yuno’s most straightforward solution with pre-built UI and automatic payment method display. Choose your platform and follow the steps to start process 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.5/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
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.)
    yuno.continuePayment();
}
});

// Mount payment form
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', () => {
    yuno.startPayment();
});
</script>

Test with: Card 4111 1111 1111 1111, any future date, any CVVFor 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)
}

Test with: Card 4111 1111 1111 1111, any future date, any CVVFor 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()
        )
    }
}

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")
                }
            }
        }
    }
}

Test with: Card 4111 1111 1111 1111, any future date, any CVVFor a comprehensive overview of all Android SDK parameters, see Android SDK Common Reference.Complete Android guide →

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 (e.g. `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).

secure-fields integration

If you need more control over the UI than full-checkout provides, you can use secure-fields. This allows you to build your own payment forms while Yuno handles the secure data collection. Learn more about secure-fields →

Test cards

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

Overview

Full Checkout

Customization

Card Enrollment

Resources

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

Backend integration

1. Create checkout session

2. Create payment

Parameters

secure-fields integration

Test cards

Overview

Full Checkout

Customization

Card Enrollment

Resources

​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

​Backend integration

​1. Create checkout session

​2. Create payment

​Parameters

​secure-fields integration

​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

Backend integration

1. Create checkout session

2. Create payment

Parameters

secure-fields integration

Test cards