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

srcfor production is https://sdk-web.y.uno/versions-sri.json .

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 (e.g., 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, such as displaying prices to customers in their preferred currency (e.g., USD) while processing the payment in the local currency (e.g., 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 (e.g. `#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 (e.g. `FR`, `US`). Determines available payment methods and compliance.
`language`	string	No	Language code for the UI (e.g. `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` in source. 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)`	function	No	Callback invoked when the payment flow finishes. Receives the payment status (e.g. `SUCCEEDED`, `DECLINED`, `PENDING`, `REJECTED`, `CANCELED`, `ERROR`). Use for UI updates or analytics.
`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 (e.g. SDK fetching config, processing payment). Use to show or hide your own loader.

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 (e.g. 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, e.g. PIX QR).

Custom texts

Parameter	Type	Required	Description
`texts`	object	No	Custom text for payment form buttons and labels (e.g. `customerForm.submitButton`, `paymentOtp.sendOtpButton`). Use to match your application 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 (e.g. `'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 (e.g. `'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,
  elementSelector: '#root',
  countryCode: 'CO',
  language: 'es',
  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, surfaces the decline (field-level errors and a top error banner), and clones the checkout session so the next attempt reuses the same flow. Retry is enabled by the Checkout Builder / Dashboard setting settings.card.enable_payment_retry under styling.settings (default enabled). It is a server-controlled setting, not a startCheckout() argument. It applies to non-enrolled card payments only — enrolled/vaulted cards are excluded. Payment retry is supported across all four Web integrations: Seamless, Full Checkout, Lite, and Secure Fields.

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 (e.g. 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 (e.g. 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, and 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 });

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 (e.g. `US`, `BR`). Determines available enrollment options. See Country coverage.
`language`	string	No	Language code for the UI (e.g. `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 (e.g., `'#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, so no vaulting will occur. For enrollment flows, see Enrollment flows (Web).

Overview

Seamless SDK

Lite SDK

Headless SDK

Customization

Card Enrollment

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

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

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

​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

​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

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

Enrollment parameters (full reference)

Mount external buttons

Parameters

Unmounting buttons

Enrolling payment methods