Installments

Register the optional onInstallmentSelected callback to keep your cart total in sync with the installment plan the shopper picks in the card form. The SDK notifies you when a default installment is pre-selected and every time the shopper changes the selection. It also notifies you when the plan is recalculated (for example, after a BIN change). The callback is optional on all platforms: if you don’t register it, the SDK behavior is unchanged. Exceptions thrown inside your callback are caught by the SDK and never interrupt the payment flow.

Platform	Available from	Where to register
Web	SDK `1.6.7`	`card.onInstallmentSelected` in `startCheckout`
iOS	SDK `2.21.0`	`onInstallmentSelected(_:)` on `YunoPaymentDelegate`
Android	SDK `2.20.0`	`onInstallmentSelected` parameter of `startCheckout`

Implementation

Web
iOS
Android

Supply your own installment options with `onGetInstallments`

Available from Web SDK 1.6.7. Pass onGetInstallments inside the card options; the SDK calls it once it knows the card’s BIN and renders whatever you return in the installments selector. The callback has a 10-second timeout; if it times out, throws an error, or returns an empty array, undefined, or nothing, the SDK falls back to the installment plans configured in Yuno.

await yuno.startCheckout({
  checkoutSession: session.checkout_session,
  elementSelector: '#payment-form',
  countryCode: 'BR',
  card: {
    onGetInstallments: async ({ bin, brand, cardType, amount, currency }) => {
      const plans = await fetch(`/api/installments?bin=${bin}&amount=${amount}`).then((r) => r.json())
      return plans.map((plan) => ({
        installment: plan.count,
        label: plan.label,
        amount: { currency, value: plan.value, total_value: plan.total },
      }))
    },
  },
  // ...
})

The callback receives a single object argument and may be async:

type OnGetInstallments = (args: {
  bin: string
  brand: string
  cardType: string
  issuerCode?: string
  issuerName?: string
  amount?: string
  currency?: string
}) => MerchantInstallmentOption[] | void | Promise<MerchantInstallmentOption[] | void>

type MerchantInstallmentOption = {
  installment: number
  label: string
  amount?: {
    currency: string
    value: string
    total_value: string
  }
  additionalData?: Record<string, unknown>
}

Argument	Type	Description
`bin`	`string`	The card’s BIN (first digits), resolved by Yuno. The callback is not called until the BIN is known.
`brand`	`string`	Card brand, e.g. `VISA`, `MASTERCARD`.
`cardType`	`string`	`CREDIT` or `DEBIT`.
`issuerCode`, `issuerName`	`string`	Issuing bank, when Yuno can resolve it.
`amount`, `currency`	`string`	The checkout session amount as a string and its currency.

Return field	Type	Description
`installment`	`number`	Number of installments, e.g. `3`. Used as the option key, so keep it unique.
`label`	`string`	The exact text rendered in the selector, in the shopper’s language.
`amount`	`object`	Optional `currency`, `value` (per installment) and `total_value`, as strings. Passed through to `onInstallmentSelected`.
`additionalData`	`object`	Optional. Accepted by the type but currently omitted from `onInstallmentSelected` (reserved for future use).

The SDK calls onGetInstallments again whenever the BIN or the amount changes, and ignores a stale response if a newer call has started. Options you return are reported to onInstallmentSelected with isMerchantInstallment: true.

React to the shopper’s choice with `onInstallmentSelected`

Pass the callback inside the card options of startCheckout:

await yuno.startCheckout({
  checkoutSession: session.checkout_session,
  elementSelector: '#payment-form',
  countryCode: 'BR',
  card: {
    onInstallmentSelected: ({ installment, label, amount, isMerchantInstallment }) => {
      // Update your cart total, e.g. with amount?.total_value
      console.log('Installment selected:', { installment, label, amount, isMerchantInstallment })
    },
  },
  // ...
})

The callback receives a single object argument:

type OnInstallmentSelected = (args: {
  installment: number
  label: string
  amount?: {
    currency: string
    value: string
    total_value: string
  }
  additionalData?: Record<string, unknown>
  isMerchantInstallment: boolean
}) => void

Field	Type	Description
`installment`	`number`	Number of installments selected (e.g. `3`).
`label`	`string`	The exact installment label rendered in the form, localized (e.g. `3x de R$875.00 - Total R$2,625.00`).
`amount`	`object`	Optional. `currency`, `value`, and `total_value` as raw strings, exactly as reported by the installments plan.
`additionalData`	`object`	Reserved for future use. Currently always `undefined`.
`isMerchantInstallment`	`boolean`	`true` when the selected option was supplied by your own `onGetInstallments` callback (merchant installments); `false` for Yuno-provided plans.

Firing semantics:

Fires with the current selection as soon as the plan renders and a default installment is pre-selected, so your total is correct from first paint.
Fires on every selection the shopper makes.
Re-fires the current selection when the available options change (for example, a BIN change recalculates the plan).
Does not fire when installments stop being available. There is no clear notification on Web.
Works across all card flows, including secure fields and Click to Pay.

Implement the optional onInstallmentSelected(_:) method of YunoPaymentDelegate:

class ViewController: UIViewController, YunoPaymentDelegate {

    // ... required YunoPaymentDelegate implementation ...

    func onInstallmentSelected(_ installmentSelected: YunoInstallmentSelected?) {
        guard let installmentSelected else {
            // Installments are no longer available — restore your base total
            return
        }
        // Update your cart total, e.g. with installmentSelected.amount?.totalValue
    }
}

The method receives a YunoInstallmentSelected? payload:

@objc public final class YunoInstallmentSelected: NSObject {
    @objc public let installment: Int
    @objc public let label: String
    @objc public let amount: YunoInstallmentAmount?
    @objc public let additionalData: [String: Any]?
}

@objc public final class YunoInstallmentAmount: NSObject {
    @objc public let currency: String
    @objc public let value: String
    @objc public let totalValue: String
}

Field	Type	Description
`installment`	`Int`	Number of installments selected (e.g. `3`).
`label`	`String`	The exact installment label rendered in the form, localized (e.g. `3x of R$ 500,31 - Total R$ 1.500,93`).
`amount`	`YunoInstallmentAmount?`	`currency`, `value`, and `totalValue` as raw strings, exactly as reported by the installments plan.
`additionalData`	`[String: Any]?`	The `additional_data` object of the selected option, when the installments service provides it.

Firing semantics:

Fires once when a default installment is pre-selected as the plan loads, so your total is correct from first paint.
Fires on every selection the shopper makes, and with the recalculated default after the plan changes (for example, a BIN change).
Fires once with nil when a previously reported selection no longer applies (for example, the shopper switches to a card without installments). Restore your base total. It is never called with nil before the first selection is reported.
Delivered on the main thread. The method is optional; omitting it keeps the SDK behavior unchanged.

Pass the callback when calling startCheckout:

startCheckout(
  checkoutSession = "checkout_session",
  countryCode = "country_code_iso",
  callbackPaymentState = { state, subState, message -> /* ... */ },
  onInstallmentSelected = { selection ->
    if (selection != null) {
      // Update your cart total, e.g. with selection.amount?.totalValue
    } else {
      // Installments are no longer available — restore your base total
    }
  },
)

The callback receives an InstallmentSelected? payload:

data class InstallmentSelected(
    val installment: Int,
    val label: String,
    val amount: InstallmentAmount? = null,
    val additionalData: Map<String, Any?>? = null,
)

data class InstallmentAmount(
    val currency: String,
    val value: String,
    val totalValue: String,
)

Field	Type	Description
`installment`	`Int`	Number of installments selected (e.g. `3`).
`label`	`String`	The exact installment label rendered in the form, localized (e.g. `3x de R$875.00 - Total R$2,625.00`).
`amount`	`InstallmentAmount?`	`currency`, `value`, and `totalValue` as raw strings, exactly as reported by the installments plan.
`additionalData`	`Map<String, Any?>?`	Reserved for future use. Currently always `null`.

Firing semantics:

Fires once when a default installment is pre-selected as the plan renders, so your total is correct from first paint.
Fires on every selection the shopper makes, and with the recalculated default after the plan changes (for example, a BIN change).
Fires once with null when installments stop being available after a selection was already reported (for example, the shopper switches to a card without installments). Restore your base total.
Does not fire when the card form renders without installments. The callback runs on the main thread, and registering no callback keeps the SDK behavior unchanged.

Overview

Seamless SDK

Lite SDK

Headless SDK

Card Enrollment

Additional Features

Resources

Additional Platforms

Web Frameworks

External Native Modules

Implementation

Supply your own installment options with `onGetInstallments`

React to the shopper’s choice with `onInstallmentSelected`

​Implementation

​Supply your own installment options with onGetInstallments

​React to the shopper’s choice with onInstallmentSelected

Implementation

Supply your own installment options with `onGetInstallments`

React to the shopper’s choice with `onInstallmentSelected`