Web Reference

Parameters, customizations, and advanced features for all Web SDK flows. See Quickstart guide and Choose the Right Integration for You for introductory information.

TypeScript support

TypeScript: Yuno provides a TypeScript library for all available methods.

Subresource Integrity (SRI)

This browser security feature lets you ensure a loaded script has not been tampered with. You provide a cryptographic hash alongside the script URL. The browser verifies the downloaded bytes match the declared hash before executing the code.

Integrity: Guarantees the exact code built and published is what runs in the browser.
Immutability: When paired with full semantic version URLs, it ensures stable, reproducible integrations.
Defense-in-depth: Mitigates risks from supply-chain or transport-layer compromise.

URL formats

When implementing SRI, use the full semantic version URL format to ensure immutable, tamper-evident integrations.

Full (immutable) URL with SRI: Full semantic version path used for locked, tamper-evident integrations with an SRI hash.
Partial (mutable) URL: Version with major and minor (for example, v1.9). This version will receive patch improvements. This is useful if you like to avoid updates in your code base.

How to integrate the SDK with SRI

Replace src and integrity with the environment/version you target. crossorigin="anonymous" lets the browser validate the SRI for cross-origin scripts. The hash can be found in versions-sri.json at latest.integrity or within the history array.

<script
  src="https://sandbox.y.uno/sdk-static-bundles-ms/sdk-web/v1.9.4/main.js"
  integrity="sha384-<paste-hash-here>"
  crossorigin="anonymous"></script>

The example above targets sandbox. For production, use the url published alongside the hash in versions-sri.json — each entry pairs a full-version url with the integrity that matches it, for example https://prod.y.uno/sdk-static-bundles-ms/sdk-web/v1.10.6/main.js.

SRI only works with these full-version URLs. The global paths such as https://sdk-web.y.uno/v1.10/main.js are republished on every patch release, so no hash stays valid for them and none is published.

Using NPM package

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

const yuno = await loadScript({
  sri: true
})

Validation notes

Open DevTools Network tab and confirm main.js returns 200 from the full-version path.
Verify the response headers allow cross-origin fetches for static assets if served from a distinct origin (crossorigin="anonymous" is set).
Ensure the integrity attribute exactly matches the generated hash, including the sha384- prefix.
Any change to main.js changes the hash. When changing versions, always regenerate or retrieve the new sha384 value and update the integrity attribute.

SRI troubleshooting

Hash mismatchs cause the script to fail execution with an integrity error (for example, you updated the file but not the hash). To fix, rebuild, retrieve the new sha384 from versions-sri.json, and update integrity.
Browser blocks SRI on cross-origin request when the crossorigin attribute is missing or CORS is restrictive. To fix, add crossorigin="anonymous" and configure the static hosting to allow cross-origin fetches for JS assets.

Key parameters (checkout session creation)

When creating a checkout session on your backend, the following parameters are commonly used across web SDKs:

Parameter	Required	Description
`amount`	Yes	The primary transaction amount object containing `currency` (ISO 4217 code) and `value` (numeric amount in that currency).
`alternative_amount`	No	An alternative currency representation of the transaction amount with the same structure as `amount` (`currency` and `value`). Useful for multi-currency scenarios. For example, you can display prices to customers in their preferred currency (for example, USD) while processing the payment in the local currency (for example, COP).

Payment and checkout parameters (full reference)

Parameters for await yuno.startCheckout(), await yuno.mountCheckout(), and related payment flows. All parameters used in Payment flows (Web) are listed here with full detail.

Core parameters

Parameter	Type	Required	Description
`checkoutSession`	string	Yes	Checkout session ID returned from your backend (Create checkout session API). Required for all payment flows.
`elementSelector`	string	No*	CSS selector for the element where the SDK mounts (for example, `#root`). Deprecated when used alone; prefer `renderMode.elementSelector` object to control APM and action areas independently. *Required when `renderMode.type` is `'element'` and using the object form.
`countryCode`	string	Yes	ISO country code where the payment runs (for example, `FR`, `US`). Determines available payment methods and compliance.
`language`	string	No	Language code for the UI (for example, `fr-FR`, `en-US`). Defaults to browser language when available. See Supported languages.
`showLoading`	boolean	No	When `true`, shows the SDK loading spinner. Default `true`. Remains visible until `hideLoader()` or `await yuno.continuePayment()` is called.
`showPaymentStatus`	boolean	No	When `true`, shows the payment result screen after the flow completes. Optional.
`issuersFormEnable`	boolean	No	When `true`, shows the issuer (bank) list form. Default `true`. Optional.

Callbacks

Parameter	Type	Required	Description
`yunoCreatePayment(oneTimeToken)`	function	Yes	Callback invoked when the user completes the card/APM step. Receive the one-time token; send it to your backend to create the payment via the API; then `await yuno.continuePayment()` to resume the flow.
`yunoPaymentResult(status, subStatus)`	function	No	Callback invoked when the payment flow finishes. Receives the payment status (for example, `SUCCEEDED`, `DECLINED`, `PENDING`, `REJECTED`, `CANCELED`, `ERROR`) and an optional `subStatus` qualifying it. Use for UI updates or analytics. See Shopper-cancelled steps.
`yunoError(message, data)`	function	No	Callback invoked when an error occurs during the flow. Receives an error message and optional data object for debugging.
`onLoading`	function	No	Callback invoked when loading state changes (for example, SDK fetching config, processing payment, payment retry cloning a session). Use to show or hide your own loader.

Shopper-cancelled steps

Some steps render in a modal the shopper can dismiss: the 3DS challenge (closing it with the X or pressing the browser back button), and payment-instruction screens such as vouchers or payment codes. When that happens, the SDK reports:

yunoPaymentResult('PENDING', 'CANCELLED_BY_USER')

No yunoError is emitted for these steps. Dismissing the modal closes the SDK UI, but it does not cancel the payment. The payment stays in flight and is resolved by the provider and by Yuno’s backend. Yuno’s backend remains the source of truth for the final status. A 3DS challenge in particular runs inside the issuer’s own iframe, so the SDK cannot determine whether authentication already completed at the moment the shopper closes the modal. Reporting a terminal cancellation there could contradict a payment that goes on to be approved.

CANCELLED_BY_USER is produced by the SDK to describe the shopper’s gesture. It is not a payment sub-status and does not appear in the Payment status reference.

Branch on subStatus to detect this case:

yunoPaymentResult(status, subStatus) {
  if (subStatus === 'CANCELLED_BY_USER') {
    // The shopper dismissed the step. The payment is still being resolved.
    // Wait for the webhook or query the payment before showing a final outcome.
    return;
  }
  // ...handle the final status
}

Card form options (`card`)

Parameter	Type	Required	Description
`card.styles`	string	No	Custom CSS string injected into the iframe to style the card form. Use to match your brand.
`card.cardSaveEnable`	boolean	No	When `true`, shows a checkbox to save or enroll the card for future use. Default `false`. Requires backend support for vaulting.
`card.texts`	object	No	Custom text for card form buttons and labels. Keys depend on SDK version (for example, placeholders, button labels).
`card.onChange`	function	No	Callback when card form state changes (loading, completed, network selected, reset). Receives `{ error, data }`; `data` can include IIN/BIN and instalment options. Use BIN for real-time tax calculations.
`card.isCreditCardProcessingOnly`	boolean	No	When `true`, forces card transactions to process as credit only. Useful where the card can act as both credit and debit.

Render mode

Parameter	Type	Required	Description
`renderMode`	object	No	Controls how payment forms are displayed. Omit to use defaults.
`renderMode.type`	string	No	`'modal'` (default) or `'element'`. Modal shows forms in an overlay; element embeds in the given DOM element.
`renderMode.elementSelector`	object	No*	Required if `type` is `'element'`. Provide `apmForm` (selector where APM UI is rendered) and `actionForm` (selector for button/area that opens provider-specific steps, for example PIX QR).

Custom texts

Parameter	Type	Required	Description
`texts`	object	No	Custom text for payment form buttons and labels (for example, `customerForm.submitButton`, `paymentOtp.sendOtpButton`). Use to match your app’s language or branding.

Express button styling (`externalButtons`)

The externalButtons property in startCheckout and startSeamlessCheckout (SDK 1.6+) allows merchants to customize the appearance of Google Pay, Apple Pay, and PayPal express buttons. All properties are optional; sensible defaults are used when not provided.

await yuno.startCheckout({
  // ... other config
  externalButtons: {
    googlePay: { /* Google Pay options */ },
    applePay: { /* Apple Pay options */ },
    paypal: { /* PayPal options */ },
  },
})

The externalButtons configuration applies to all flows that render express buttons (including mountCheckout, mountExternalButtons, and mountSeamlessExternalButtons), as long as startCheckout or startSeamlessCheckout was called first with the configuration.

Google Pay

externalButtons: {
  googlePay: {
    buttonColor: 'default',
    buttonType: 'pay',
    buttonRadius: 30,
    buttonLocale: 'en',
    buttonSizeMode: 'fill',
    buttonWidth: 240,
    buttonHeight: 48,
  }
}

Property	Type	Default	Description
`buttonColor`	`'default'` \| `'black'` \| `'white'`	Google decides	Button background color
`buttonType`	`'book'` \| `'buy'` \| `'checkout'` \| `'donate'` \| `'order'` \| `'pay'` \| `'plain'` \| `'subscribe'`	`'pay'`	Button label text
`buttonRadius`	`number`	`30`	Border radius in px
`buttonLocale`	`string`	SDK language	ISO 639-1 alpha-2 lowercase (for example, `'en'`, `'es'`, `'pt'`)
`buttonSizeMode`	`'fill'` \| `'static'`	`'fill'`	Whether the button fills its container or uses a fixed size
`buttonWidth`	`number`	`100%`	Wrapper width in px
`buttonHeight`	`number`	`40`	Wrapper height in px

Apple Pay

externalButtons: {
  applePay: {
    buttonType: 'buy',
    buttonStyle: 'black',
    locale: 'en',
    buttonWidth: 200,
    buttonHeight: 48,
    buttonBorderRadius: 4,
  }
}

Property	Type	Default	Description
`buttonType`	`'plain'` \| `'add-money'` \| `'book'` \| `'buy'` \| `'check-out'` \| `'contribute'` \| `'donate'` \| `'order'` \| `'pay'` \| `'reload'` \| `'rent'` \| `'set-up'` \| `'subscribe'` \| `'support'` \| `'tip'` \| `'top-up'`	`'plain'`	Button label text
`buttonStyle`	`'black'` \| `'white'` \| `'white-outline'`	`'black'`	Button background style
`locale`	`string`	SDK language	ISO 639-1 alpha-2 lowercase (for example, `'en'`, `'es'`, `'pt'`)
`buttonWidth`	`number`	`100%`	Wrapper width in px
`buttonHeight`	`number`	`40`	Wrapper height in px
`buttonBorderRadius`	`number`	`30`	Border radius in px

PayPal

externalButtons: {
  paypal: {
    color: 'gold',
    shape: 'rect',
    label: 'paypal',
    layout: 'vertical',
    height: 45,
    width: 200,
    borderRadius: 4,
  }
}

Property	Type	Default	Description
`color`	`'gold'` \| `'blue'` \| `'silver'` \| `'white'` \| `'black'`	PayPal decides	Button background color
`shape`	`'rect'` \| `'pill'` \| `'sharp'`	`'pill'`	Button shape
`label`	`'paypal'` \| `'checkout'` \| `'buynow'` \| `'pay'` \| `'installment'`	PayPal decides	Button label text
`layout`	`'vertical'` \| `'horizontal'`	PayPal decides	Button layout direction
`height`	`number`	`40`	Button height in px (valid range: 25–55)
`width`	`number`	`100%`	Wrapper width in px
`borderRadius`	`number`	PayPal decides (by shape)	Border radius in px

Full example

const yuno = await window.Yuno.initialize(publicApiKey)

await yuno.startCheckout({
  checkoutSession,
  countryCode: 'CO',
  language: 'es',
  renderMode: {
    type: 'element',
    elementSelector: {
      apmForm: '#apm-root',
      actionForm: '#action-root',
    },
  },
  externalButtons: {
    googlePay: {
      buttonColor: 'black',
      buttonType: 'pay',
      buttonRadius: 4,
      buttonSizeMode: 'fill',
    },
    applePay: {
      buttonType: 'buy',
      buttonStyle: 'black',
      buttonBorderRadius: 4,
    },
    paypal: {
      color: 'blue',
      shape: 'rect',
      label: 'pay',
      height: 45,
      borderRadius: 4,
    },
  },
  // ... rest of config
})

Payment retry

Payment retry lets a shopper fix and re-submit a card payment after it comes back DECLINED or ERROR, without restarting the checkout. Instead of tearing down the card form, the SDK keeps it open and surfaces the decline (field-level errors and a top error banner). It also clones the checkout session so the next attempt reuses the same flow. Retry is disabled by default. Yuno enables it per organization on request through a server-side flag — it is not a Dashboard or Checkout Builder toggle. It is a server-controlled setting, not a startCheckout() argument. It applies to non-enrolled card payments only. Enrolled cards, vaulted cards, and external-button payments are excluded. Payment retry is supported across all four Web integrations: Seamless, Full Checkout, Lite, and Secure Fields.

Retry in Lite shipped in SDK v1.9.11.

Behavior by integration

Integration	What you need to do
Seamless	Automatic. The SDK keeps the card form open and drives the retry itself. No extra integration required.
Full Checkout	Manual. After creating the payment on your backend, check the response and call `continuePayment` (see below).
Lite	Manual. Same as Full Checkout.
Secure Fields	Manual. Same as Full Checkout.

Triggering retry in Full Checkout, Lite, and Secure Fields

For these three flows, after your backend creates the payment you must inspect the payment response and drive the SDK accordingly:

Card payment that failed (payment_method.type === 'CARD' and status is DECLINED or ERROR): call continuePayment to run the retry. The card form stays open with the decline shown.
Additional action required (checkout.sdk_action_required === true): call continuePayment so the SDK can show the required screens (for example, 3DS or a redirect).
Nothing left for the SDK to do (status is not DECLINED/ERROR and checkout.sdk_action_required === false): the SDK will not tear itself down, so you must unmount it manually with unmountSdk.

// In your yunoCreatePayment callback, after creating the payment on your backend:
const payment = await createPaymentOnYourBackend(oneTimeToken);

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

if (isCard && failed) {
  // Runs the retry flow: keeps the card form open with the decline shown.
  await yuno.continuePayment();
} else if (actionRequired) {
  // Additional action needed (for example, 3DS or redirect).
  await yuno.continuePayment({ showPaymentStatus: true });
} else {
  // No retry and no action required: clean up the SDK yourself.
  await yuno.unmountSdk();
}

If the payment method is CARD and the status is DECLINED or ERROR, you must call continuePayment. If you don’t, the card form will not close automatically. The shopper is left on the open form with no next step.When the status is anything other than DECLINED/ERROR and checkout.sdk_action_required is false, call unmountSdk to remove the SDK from the DOM. It does not unmount on its own in these flows.

Secure Fields: set the checkoutSession on the secureFields({ ... }) object, and do not pass it to generateTokenWithInformation({ ... }).Retry is armed when the SDK initializes the secure fields with a checkoutSession. On each retry, the SDK swaps in a freshly cloned session internally. If you also pass checkoutSession to generateTokenWithInformation, that fixed value overrides the cloned one and breaks the retry attempt.

// ✅ Correct: checkoutSession only on secureFields
const secureFields = await yuno.secureFields({
  checkoutSession,
  // ...other options
});

const token = await secureFields.generateTokenWithInformation({ /* no checkoutSession */ });

// ❌ Incorrect: checkoutSession passed to generateTokenWithInformation overrides the cloned session on retry
const token = await secureFields.generateTokenWithInformation({ checkoutSession });

Retry lifecycle and callbacks

On a retried attempt the SDK does not fire yunoPaymentResult and does not mount the status page. Instead, it delivers the cloned checkout session to your onLoading callback:

onLoading: ({ type, data }) => {
  if (type === 'PAYMENT_RETRY') {
    // A fresh checkout session has been cloned for the retry.
    const newCheckoutSession = data.newCheckoutSession;
    // The SDK will NOT fire yunoPaymentResult for this retry step.
    // The shopper stays on the card form — no additional action needed.
  }
}

Each retry attempt flows through yunoCreatePayment → your backend → continuePayment (or automatic in Seamless) without a yunoPaymentResult callback between attempts. yunoPaymentResult fires only when the flow finishes — either the payment succeeds, the shopper exits, or the payment fails without being retryable.

updateCheckoutSession

updateCheckoutSession(checkoutSession) replaces the active checkout session without unmounting the SDK. Use it to let the shopper switch to a different payment method after a failed payment.

// After a failed payment, inject a new session so the shopper can pick another method:
await yuno.updateCheckoutSession(newCheckoutSession);

The SDK keeps the current UI mounted and swaps the checkout session id in internal state. Nothing is re-fetched: the payment-method list, settings, styling, and country data are all fetched once at mount and stay on the mount-time session. If the new session exposes a different set of payment methods, styling, or country configuration, you must unmount and re-mount the SDK.

yuno.updateCheckoutSession() automatically propagates to the Secure Fields instance — there is no need to call it on the SF instance directly.

Enrollment parameters (full reference)

Parameters for await yuno.mountEnrollment(). All parameters used in Enrollment flows (Web) are listed here with full detail.

Parameter	Type	Required	Description
`customerSession`	string	Yes	Customer session ID from your backend (Create customer session API). Required. Associates the enrolled payment method with a specific customer.
`countryCode`	string	Yes	ISO country code (for example, `US`, `BR`). Determines available enrollment options. See Country coverage.
`language`	string	No	Language code for the UI (for example, `en`, `en-US`). Defaults to browser language when available.
`showLoading`	boolean	No	When `true`, shows the loading spinner during enrollment. Default `true`.
`onLoading`	function	No	Callback when loading state changes during enrollment.
`elementSelector`	string	No	CSS selector where the enrollment form mounts. Required when not using default modal behavior.
`card`	object	No	Card form options (same structure as payment flows: `type`, `styles`, `texts`, `onChange`, `isCreditCardProcessingOnly`, etc.).
`yunoEnrollmentStatus`	function	No	Callback when enrollment ends. Receives `vaultedToken` and `status`. Status values: `CREATED`, `EXPIRED`, `REJECTED`, `READY_TO_ENROLL`, `ENROLL_IN_PROCESS`, `UNENROLL_IN_PROCESS`, `ENROLLED`, `DECLINED`, `CANCELED`, `ERROR`, `UNENROLLED`.
`issuersFormEnable`	boolean	No	When `true`, shows the issuer (bank) list form. Optional.
`texts`	object	No	Custom text for enrollment form buttons and labels.

Mount external buttons

Use the mountExternalButtons method to render PayPal, Google Pay, and Apple Pay buttons in custom locations within your UI. This gives you control over where these buttons are displayed.

await yuno.mountExternalButtons([
  {
    paymentMethodType: 'APPLE_PAY',
    elementSelector: '#apple-pay',
  },
  {
    paymentMethodType: 'GOOGLE_PAY',
    elementSelector: '#google-pay',
  },
  {
    paymentMethodType: 'PAYPAL',
    elementSelector: '#paypal',
  },
]);

Parameters

Parameter	Description
`paymentMethodType`	The payment method type. Must be `'APPLE_PAY'`, `'GOOGLE_PAY'`, or `'PAYPAL'`.
`elementSelector`	The CSS selector for the HTML element where the button should be rendered (for example, `'#apple-pay'`, `'.button'`).

Unmounting buttons

You can unmount a single external button by payment method type:

await yuno.unmountExternalButton('APPLE_PAY');

Or unmount all external buttons at once:

await yuno.unmountAllExternalButtons();

Enrolling payment methods

You can enroll payment methods (store cards for future use) directly during the payment flow by setting payment_method.vault_on_success = true in the checkout session creation. When vault_on_success is set to true:

The payment method will be automatically enrolled if the payment status is SUCCEEDED
If the payment does not succeed, no vaulting will occur
The payment response will include a vaulted_token that you can use for future transactions

Example:

{
    "account_id": "...",
    "payment_method": {
        "vault_on_success": true
    }
}

To generate and receive a vaulted_token when vault_on_success = true, the payment must reference an existing Yuno customer through customer_payer.id in the checkout session. Creating or sending the customer data inline inside the payment request does not create the customer on our side. As a result, no vaulting will occur. For enrollment flows, see Enrollment flows (Web).

Overview

Seamless SDK

Lite SDK

Headless SDK

Card Enrollment

Additional Features

Resources

Additional Platforms

External Native Modules

TypeScript support

Subresource Integrity (SRI)

URL formats

How to integrate the SDK with SRI

Using NPM package

Validation notes

SRI troubleshooting

Key parameters (checkout session creation)

Payment and checkout parameters (full reference)

Core parameters

Callbacks

Shopper-cancelled steps

Card form options (`card`)

Render mode

Custom texts

Express button styling (`externalButtons`)

Google Pay

Apple Pay

PayPal

Full example

Payment retry

Behavior by integration

Triggering retry in Full Checkout, Lite, and Secure Fields

Retry lifecycle and callbacks

updateCheckoutSession

Enrollment parameters (full reference)

Mount external buttons

Parameters

Unmounting buttons

Enrolling payment methods

​TypeScript support

​Subresource Integrity (SRI)

​URL formats

​How to integrate the SDK with SRI

​Using NPM package

​Validation notes

​SRI troubleshooting

​Key parameters (checkout session creation)

​Payment and checkout parameters (full reference)

​Core parameters

​Callbacks

​Shopper-cancelled steps

​Card form options (card)

​Render mode

​Custom texts

​Express button styling (externalButtons)

​Google Pay

​Apple Pay

​PayPal

​Full example

​Payment retry

​Behavior by integration

​Triggering retry in Full Checkout, Lite, and Secure Fields

​Retry lifecycle and callbacks

​updateCheckoutSession

​Enrollment parameters (full reference)

​Mount external buttons

​Parameters

​Unmounting buttons

​Enrolling payment methods

TypeScript support

Subresource Integrity (SRI)

URL formats

How to integrate the SDK with SRI

Using NPM package

Validation notes

SRI troubleshooting

Key parameters (checkout session creation)

Payment and checkout parameters (full reference)

Core parameters

Callbacks

Shopper-cancelled steps

Card form options (`card`)

Render mode

Custom texts

Express button styling (`externalButtons`)

Google Pay

Apple Pay

PayPal

Full example

Payment retry

Behavior by integration

Triggering retry in Full Checkout, Lite, and Secure Fields

Retry lifecycle and callbacks

updateCheckoutSession

Enrollment parameters (full reference)

Mount external buttons

Parameters

Unmounting buttons

Enrolling payment methods