Web SDK Reference - Yuno API Documentation

Installation

Add the Yuno Web SDK to your page via script tag or npm.

Script Tag
npm

<script
  src="https://sdk-web.y.uno/v1/static/js/main.min.js"
  integrity="sha384-XXXX"
  crossorigin="anonymous"
></script>

Use Subresource Integrity (SRI) by including the integrity attribute. Request the latest hash from support@y.uno when upgrading.

npm install @yuno-payments/sdk-web

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

Initialization

Initialize the SDK before mounting any checkout component. Pass your public API key as a string:

const yuno = Yuno.initialize("YOUR_PUBLIC_API_KEY");

Initialization Parameters

Parameter	Type	Required	Description
`publicApiKey`	`string`	Yes	Your Yuno public API key from Dashboard > API Keys. Passed as the first positional argument (string, not object)

The first argument must be a string (your public API key), not a configuration object. Passing an object will cause: publicApiKey=[object Object] is not valid. Never include your private secret key in client-side code.

Seamless Checkout Configuration

Start Seamless Checkout by passing a configuration object with all options.

yuno.startSeamlessCheckout({
  checkoutSession: "438413b7-4921-41e4-b8f3-28a5a0141638",
  elementSelector: "#root",
  countryCode: "CO",
  language: "en",
  showLoading: true,
  issuersFormEnable: true,
  showPaymentStatus: true,
  renderMode: {
    type: "modal",
  },
  card: {
    type: "extends",
    cardSaveEnable: false,
  },
  async yunoCreatePayment(oneTimeToken, tokenWithInformation) {
    await createPayment({ oneTimeToken, checkoutSession });
    yuno.continuePayment({ showPaymentStatus: true });
  },
  yunoPaymentMethodSelected(data) {
    console.log("Selected:", data);
  },
  yunoPaymentResult(data) {
    console.log("Result:", data);
  },
  yunoError(error) {
    console.error("Error:", error);
  },
});

Checkout Configuration Properties

Property	Type	Required	Description
`checkoutSession`	`string`	Yes	Checkout session ID from the Create Checkout Session API
`elementSelector`	`string`	Yes	CSS selector for the container element (e.g., `"#root"`)
`countryCode`	`string`	Yes	ISO 3166-1 alpha-2 country code
`language`	`string`	No	UI language override: `"en"`, `"es"`, `"pt"`
`showLoading`	`boolean`	No	Show loading indicator during SDK operations. Default: `true`
`issuersFormEnable`	`boolean`	No	Display bank/issuer selection dropdown for methods that require it. Default: `false`
`showPaymentStatus`	`boolean`	No	Show payment status screen after completion. Default: `true`
`renderMode`	`object`	No	Controls how the checkout form renders. See Render Modes
`card`	`object`	No	Card form configuration. See Card Form Options

Callbacks

yunoCreatePayment(oneTimeToken, tokenWithInformation)

Called when the customer submits payment and Yuno generates a one-time token. Use this to create the payment on your server, then call yuno.continuePayment().

async yunoCreatePayment(oneTimeToken, tokenWithInformation) {
  // oneTimeToken: string — single-use token for payment creation
  // tokenWithInformation: object — token plus payment method metadata
  const response = await fetch('/api/payments', {
    method: 'POST',
    body: JSON.stringify({ token: oneTimeToken, session: checkoutSession }),
  });

  if (response.ok) {
    yuno.continuePayment({ showPaymentStatus: true });
  }
}

Parameter	Type	Description
`oneTimeToken`	`string`	Single-use token to pass to the Create Payment API
`tokenWithInformation`	`object`	Token with additional metadata (payment method type, last four digits, brand)

yunoPaymentResult(paymentResult)

Called with the final payment outcome after the flow completes.

yunoPaymentResult(data) {
  // data.status: "SUCCEEDED" | "FAILED" | "PROCESSING" | "CANCELLED"
  // data.paymentId: string
  switch (data.status) {
    case "SUCCEEDED":
      window.location.href = `/confirmation?id=${data.paymentId}`;
      break;
    case "FAILED":
      showError(data.errorMessage);
      break;
  }
}

Always verify the final payment status server-side via webhooks or the GET Payment API. Client-side callbacks should not be the sole source of truth.

yunoPaymentMethodSelected(data)

Fires when the user selects a payment method.

yunoPaymentMethodSelected(data) {
  // data.paymentMethodType: string (e.g., "CARD", "PIX", "PSE")
  console.log("Selected method:", data.paymentMethodType);
}

yunoError(error)

Called when the SDK encounters an error.

yunoError(error) {
  // error.message: string
  // error.code: string
  console.error("SDK error:", error.message);
}

onLoading(isLoading)

Reports loading state changes during SDK operations.

onLoading(isLoading) {
  // isLoading: boolean
  document.getElementById("spinner").style.display = isLoading ? "block" : "none";
}

Render Modes

Control how the checkout form appears in the page. The checkout form opens in an overlay modal on top of your page.

renderMode: {
  type: "modal",
}

Element (Inline)

The checkout form renders inline within a specified container.

renderMode: {
  type: "element",
  elementSelector: "#checkout-container",
}

Property	Type	Required	Description
`type`	`"modal"` \| `"element"`	Yes	Render mode
`elementSelector`	`string`	Only for `"element"`	CSS selector for the inline container

Card Form Options

Configure the card payment form behavior and appearance.

card: {
  type: "extends",
  cardSaveEnable: true,
  styles: {
    base: {
      fontSize: "16px",
      color: "#333",
      fontFamily: "Inter, sans-serif",
      "::placeholder": { color: "#9CA3AF" },
    },
    focus: {
      borderColor: "#0066FF",
    },
    error: {
      color: "#EF4444",
      borderColor: "#EF4444",
    },
  },
  texts: {
    cardNumberLabel: "Card Number",
    expiryLabel: "Expiry Date",
    cvvLabel: "Security Code",
  },
  hideCardholderName: false,
  isCreditCardProcessingOnly: false,
  onChange(event) {
    console.log("Field changed:", event);
  },
}

Card Properties

Property	Type	Default	Description
`type`	`"extends"` \| `"card"` \| `"cardNumber"` \| `"cardExpiry"` \| `"cardCvv"`	`"extends"`	Card form type. `"extends"` renders the full card form. Individual types render standalone fields
`cardSaveEnable`	`boolean`	`false`	Show a “Save card for future payments” checkbox
`styles`	`object`	.	CSS customization object for card fields. Supports `base`, `focus`, `error`, `valid` states
`texts`	`object`	.	Custom label overrides for card form fields
`cardNumberPlaceholder`	`string`	`"Card number"`	Placeholder text for the card number field
`expiryPlaceholder`	`string`	`"MM/YY"`	Placeholder text for the expiry field
`cvvPlaceholder`	`string`	`"CVV"`	Placeholder text for the CVV field
`hideCardholderName`	`boolean`	`false`	Hide the cardholder name field
`isCreditCardProcessingOnly`	`boolean`	`false`	Show only credit cards, hiding debit card options
`onChange(event)`	`function`	.	Callback fired when any card field value changes

Card Field Types

Use individual field types to render standalone, embeddable card inputs:

Type	Description
`"card"`	Complete card form (number, expiry, CVV, name)
`"cardNumber"`	Card number field only
`"cardExpiry"`	Expiry date field only
`"cardCvv"`	CVV/CVC field only
`"extends"`	Extended card form integrated into checkout

Seamless Flow Methods

mountSeamlessCheckout

Mount the checkout form for a specific payment method after the customer selects one.

yuno.mountSeamlessCheckout({
  paymentMethodType: "CARD",
  vaultedToken: "vtk_abc123xyz", // optional, for saved payment methods
});

Parameter	Type	Required	Description
`paymentMethodType`	`string`	Yes	Payment method type (e.g., `"CARD"`, `"PIX"`, `"PSE"`)
`vaultedToken`	`string`	No	Vaulted token for returning customers with saved payment methods

startPayment

Trigger the payment after the customer has filled in the form.

yuno.startPayment();

continuePayment

Continue the payment flow after creating the payment on your server. Call this inside yunoCreatePayment.

yuno.continuePayment({
  showPaymentStatus: true,
});

Parameter	Type	Required	Description
`showPaymentStatus`	`boolean`	No	Show the payment status screen after completion

External Buttons

Mount Apple Pay and Google Pay buttons outside the main checkout form.

mountExternalButtons

Render wallet payment buttons in specified containers.

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

<div id="apple-pay-container"></div>
<div id="google-pay-container"></div>

unmountExternalButton

Remove a specific external payment button.

yuno.unmountExternalButton("APPLE_PAY");

Parameter	Type	Required	Description
`type`	`string`	Yes	Payment method type to remove (`"APPLE_PAY"`, `"GOOGLE_PAY"`)

unmountAllExternalButtons

Remove all mounted external payment buttons.

yuno.unmountAllExternalButtons();

Enrollment

Use the SDK to enroll (vault) payment methods for returning customers.

Enrollment Statuses

Status	Description
`CREATED`	Enrollment session created
`READY_TO_ENROLL`	Customer has submitted card details, ready to enroll
`ENROLLED`	Card successfully enrolled and vaulted
`ENROLL_FAILED`	Enrollment attempt failed
`EXPIRED`	Enrollment session expired before completion
`REJECTED`	Enrollment rejected by the provider
`DECLINED`	Enrollment declined
`UNENROLLED`	Previously enrolled card has been removed

See Card Enrollment for the complete enrollment integration guide.

TypeScript Support

The Yuno Web SDK includes TypeScript type definitions. Import types directly:

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

const yuno = Yuno.initialize("YOUR_PUBLIC_API_KEY");

Key type definitions:

Type	Description
`StartCheckoutArgs`	Configuration for `startCheckout()` (checkoutSession, countryCode, callbacks, etc.)
`SeamlessCheckoutConfig`	Seamless checkout startup configuration
`OneTimeToken`	One-time token with payment method metadata
`CardOptions`	Card form configuration options
`RenderMode`	Render mode configuration (`"modal"` or `"element"`)

Subresource Integrity (SRI)

When loading the SDK via script tag, use SRI to ensure the script has not been tampered with:

<script
  src="https://sdk-web.y.uno/v1/static/js/main.min.js"
  integrity="sha384-{hash}"
  crossorigin="anonymous"
></script>

Request the current SRI hash from support@y.uno. Update the hash whenever you upgrade the SDK version.

Complete Initialization Example

A full example with all configuration options:

const yuno = Yuno.initialize("YOUR_PUBLIC_API_KEY");

yuno.startSeamlessCheckout({
  checkoutSession: "session-uuid",
  elementSelector: "#checkout",
  countryCode: "CO",
  language: "es",
  showLoading: true,
  issuersFormEnable: true,
  showPaymentStatus: true,
  renderMode: {
    type: "element",
    elementSelector: "#checkout-form",
  },
  card: {
    type: "extends",
    cardSaveEnable: true,
    hideCardholderName: false,
    isCreditCardProcessingOnly: false,
    cardNumberPlaceholder: "Card number",
    expiryPlaceholder: "MM/YY",
    cvvPlaceholder: "CVV",
    styles: {
      base: {
        fontSize: "16px",
        color: "#333",
        fontFamily: "Inter, sans-serif",
        padding: "12px",
        "::placeholder": { color: "#9CA3AF" },
      },
      focus: { borderColor: "#6200EE" },
      error: { color: "#E53E3E", borderColor: "#E53E3E" },
      valid: { borderColor: "#38A169" },
    },
    onChange(event) {
      console.log("Field changed:", event);
    },
  },
  async yunoCreatePayment(oneTimeToken, tokenWithInformation) {
    const response = await fetch("/api/payments", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ token: oneTimeToken }),
    });
    if (response.ok) {
      yuno.continuePayment({ showPaymentStatus: true });
    }
  },
  yunoPaymentMethodSelected(data) {
    console.log("Selected:", data.paymentMethodType);
  },
  yunoPaymentResult(data) {
    if (data.status === "SUCCEEDED") {
      window.location.href = `/confirmation?id=${data.paymentId}`;
    }
  },
  yunoError(error) {
    console.error("SDK Error:", error.message);
  },
  onLoading(isLoading) {
    document.getElementById("spinner").hidden = !isLoading;
  },
});

// Mount external wallet buttons
await yuno.mountExternalButtons([
  { paymentMethodType: "APPLE_PAY", elementSelector: "#apple-pay" },
  { paymentMethodType: "GOOGLE_PAY", elementSelector: "#google-pay" },
]);

// Mount checkout for a specific payment method
yuno.mountSeamlessCheckout({
  paymentMethodType: "CARD",
});

// Trigger payment
yuno.startPayment();

Next Steps

Full Checkout

Pre-built UI with zero payment method management.

Seamless Checkout

Control payment method selection with SDK convenience.

Customization

Theme and style your checkout.

Card Enrollment

Vault cards for returning customers.

​Installation

​Initialization

​Initialization Parameters

​Seamless Checkout Configuration

​Checkout Configuration Properties

​Callbacks

​yunoCreatePayment(oneTimeToken, tokenWithInformation)

​yunoPaymentResult(paymentResult)

​yunoPaymentMethodSelected(data)

​yunoError(error)

​onLoading(isLoading)

​Render Modes

​Modal

​Element (Inline)

​Card Form Options

​Card Properties

​Card Field Types

​Seamless Flow Methods

​mountSeamlessCheckout

​startPayment

​continuePayment

​External Buttons

​mountExternalButtons

​unmountExternalButton

​unmountAllExternalButtons

​Enrollment

​Enrollment Statuses

​TypeScript Support

​Subresource Integrity (SRI)

​Complete Initialization Example

​Next Steps

Full Checkout

Seamless Checkout

Customization

Card Enrollment

Installation

Initialization

Initialization Parameters

Seamless Checkout Configuration

Checkout Configuration Properties

Callbacks

yunoCreatePayment(oneTimeToken, tokenWithInformation)

yunoPaymentResult(paymentResult)

yunoPaymentMethodSelected(data)

yunoError(error)

onLoading(isLoading)

Render Modes

Modal

Element (Inline)

Card Form Options

Card Properties

Card Field Types

Seamless Flow Methods

mountSeamlessCheckout

startPayment

continuePayment

External Buttons

mountExternalButtons

unmountExternalButton

unmountAllExternalButtons

Enrollment

Enrollment Statuses

TypeScript Support

Subresource Integrity (SRI)

Complete Initialization Example

Next Steps