Full SDK implementation
This page provides a step-by-step guide to implement and enable Yuno's Full Web SDK functionality in your application.
Changelog Reference:This guide covers the current SDK version. For details on previous versions, see the changelog.
Step 1: Include the library in your project
Add the following script tag to your HTML file to include the Yuno Web SDK:
<script src="https://cdn.yuno.com/sdk-web/latest/yuno-sdk-web.js"></script>
Alternatively, you can install it via npm:
npm install @yuno-payments/sdk-web
After completing the SDK integration, proceed with the following steps to implement the full checkout functionality.
TypeScript LibraryIf you are using TypeScript, Yuno provides a library to see all methods available in the Yuno Web SDK.
Step 2: Initialize SDK with the public key
Create an instance of the Yuno
class by providing a valid PUBLIC_API_KEY
. See the credentials page for more information.
Initialize the SDK with your public API key:
const yuno = await Yuno.initialize(PUBLIC_API_KEY);
Step 3: Start the checkout process
Use the yuno.startCheckout
function to start the checkout process with the necessary parameters.
See the Parameters table below for all the options you can use with startCheckout
.
For further customization or advanced/optional settings, see the Complementary Features section.
Parameters
The following table lists all the available parameters for the startCheckout
method with descriptions:
Parameter | Description |
---|---|
checkoutSession | Refers to the current payment's checkout session. Example: '438413b7-4921-41e4-b8f3-28a5a0141638' |
elementSelector | The element where the SDK will be mounted. |
countryCode | This parameter specifies the country for which the payment process is being set up. Use an ENUM value representing the desired country code. You can find the full list of supported countries and their corresponding codes on the Country Coverage page. |
language | Defines the language to be used in the payment forms. You can set it to one of the available language options:
|
onLoading | Required to receive notifications about server calls or loading events during the payment process. |
showLoading | Control the visibility of the Yuno loading/spinner page during the payment process. By default, it's true . |
issuersFormEnable | Enables the issuer's form. By default, it's true . |
showPaymentStatus | Shows the Yuno Payment Status page. You can use this option when continuing a payment as well. By default, it's true . |
card.isCreditCardProcessingOnly | Enables you to ensure that all card transactions are processed as credit only. This option is helpful in markets where cards can act as both credit and debit. To enable, set the isCreditCardProcessingOnly to true to ensure that all card transactions are processed as credit. This parameter is not required. |
yuno.startCheckout({
checkoutSession: "438413b7-4921-41e4-b8f3-28a5a0141638",
elementSelector: "#root",
countryCode: "FR",
language: "fr",
showLoading: true,
issuersFormEnable: true,
showPaymentStatus: true,
card: {
isCreditCardProcessingOnly: true,
},
onLoading: (args) => {
console.log(args);
},
yunoPaymentMethodSelected: () => {
console.log("Payment method selected");
},
yunoPaymentResult: (status) => {
console.log("Payment result:", status);
},
yunoError: (message, data) => {
console.error("Payment error:", message, data);
},
async yunoCreatePayment(oneTimeToken) {
await createPayment({ oneTimeToken, checkoutSession });
yuno.continuePayment({ showPaymentStatus: true });
},
});
Rendering ModeBy default, Yuno SDK renders as a modal. However, you can specify the element where the SDK will render. For additional information, access Render mode under the complementary features page.
onPaymentMethodSelected
EventFor all APMs, including Google Pay, Apple Pay, and PayPal,
onPaymentMethodSelected
is triggered as soon as the customer chooses the payment method (before the payment flow begins). DefineonPaymentMethodSelected
instartCheckout
beforemountCheckout
.
Step 4: Mount the SDK
Display the payment methods:
yuno.mountCheckout();
Mount with a default payment method selected:
yuno.mountCheckout({
paymentMethodType: PAYMENT_METHOD_TYPE,
vaultedToken: VAULTED_TOKEN,
});
Step 5: Initiate the payment process
Call yuno.startPayment()
to initiate the payment flow after the user selects a payment method:
const PayButton = document.querySelector("#button-pay");
PayButton.addEventListener("click", () => {
yuno.startPayment();
});
Step 6: Get the OTT (one-time token)
After the customer fills out the requested data in Yuno's payment forms, the SDK provides the one-time token. The configuration function yuno.CreatePayment(oneTimeToken)
is then triggered with the one-time token.
yunoCreatePayment(oneTimeToken);
You can also use tokenWithInformation
to receive additional information provided by the customer in the checkout, such as installments or document type/number:
yunoCreatePayment(oneTimeToken, tokenWithInformation);
Loader ManagementThe merchant is responsible for managing the loader. Yuno provides a default loader option, but merchants may implement their own loader if preferred. In that case, they are responsible for making the necessary configurations.
Step 7: Create the Payment
After completing the previous steps, proceed to create a payment. Back-to-back payment creation must be performed using the Create Payment endpoint. The merchant's backend should call this endpoint to create the payment in Yuno using the one-time token and checkout session.
Complete the IntegrationAfter Step 7, you have successfully implemented the basic payment flow. To test your integration, create a test payment using the checkout session and one-time token. For additional features and advanced configurations, see the Complementary Features section below.
ContinuePaymentmethodAfter creating a payment, Yuno requires you to integrate the
continuePayment
method from the SDK. This is necessary because some asynchronous payment methods require additional customer actions to complete the process. The API response will indicate this scenario by setting thesdk_action_required
field to true. When this occurs, you must callyuno.continuePayment()
, which will automatically present the necessary screens to the customer, allowing them to complete the payment flow without requiring you to handle each case manually.
continuePayment
return value or null
continuePayment
return value or nullFor payment methods that require merchant-side action (e.g., when the payment provider requires a redirect URL in a webview), the await yuno.continuePayment()
method returns either an object with the following structure or null:
{
action: 'REDIRECT_URL'
type: string
redirect: {
init_url: string
success_url: string
error_url: string
}
} | null
When the method returns an object, you can handle your application's payment flows that require custom redirect handling. When it returns null, no additional merchant-side action is needed.
Demo AppIn addition to the code examples provided, you can access the Demo App for a complete implementation of Yuno SDKs or go directly to the HTML and JavaScript checkout demos available on GitHub.
Complementary features
Yuno Web SDK provides additional services and configurations you can use to improve customers' experience:
Form loader
Control the use of the loader:
Parameter | Description |
---|---|
showLoading | You can hide or show the Yuno loading/spinner page. Enabling this option ensures that the loading component remains displayed until either the hideLoader() or continuePayment() function is called. The default value is true. |
yuno.startCheckout({
showLoading: true,
});
Issuer's form
Parameter | Description |
---|---|
issuersFormEnable | Configure the SDK to enable the issuer's form (bank list): |
yuno.startCheckout({
issuersFormEnable: true,
});
Render mode
Parameter | Description |
---|---|
| This optional parameter determines the mode in which the payment forms will be displayed. |
| |
| |
| Required only if the type is |
| |
|
yuno.startCheckout({
renderMode: {
type: "modal",
elementSelector: {
apmForm: "#form-element",
actionForm: "#action-form-element",
},
},
});
Card form configurations
Parameter | Description |
---|---|
card | Define specific settings for the credit card form: |
type : step or extends | |
styles : You can edit card form styles. Only you should write css, then it will be injected into the iframe. | |
cardSaveEnable : Show checkbox for save/enroll card. The default value is false. | |
texts : Custom texts in the Card forms buttons. |
yuno.startCheckout({
card: {
type: "extends",
styles: "",
cardSaveEnable: false,
texts: {},
},
});
Save card for future payments
You can display a checkbox for saving or enrolling cards using cardSaveEnable: true
. The following examples show the checkbox for both card form renders:

Rendering modes
The following screenshots show the difference between:
- Render modes
modal
andelements
for the payment method list - Render modes
step
andextends
for the credit card form

You can also choose one of the render options for the card form, step
and extends
:

Text payment form buttons
Parameter | Description |
---|---|
texts | Provide custom text for payment form buttons to match your application's language or branding: |
yuno.startCheckout({
texts: {
customerForm?: {
submitButton?: string;
}
paymentOtp?: {
sendOtpButton?: string;
}
}
})
Persist credit card form to retry payments
If a transaction is rejected, you can use the credit card form to retry a payment after the customer has entered the credit card details. To do this:
- Add the following parameter while initializing the SDK to persist the credit card form after the one-time use token is created:
yuno.startCheckout({ automaticallyUnmount: false, });
- If the transaction is rejected:
- Execute the method
yuno.notifyError()
to delete the previously entered CVV for the first transaction - Create a new checkout session and update the SDK with the new one by executing
yuno.updateCheckoutSession(checkoutsession)
- Execute the method
- Continue with the new checkout and one-time use token with the regular payment flow.
Hide Pay button
You can hide the Pay button when presenting the card or customer data form. Set showPayButton
to false
when starting the checkout with the startCheckout
function:
yuno.startCheckout({
showPayButton: false,
});
The following images show examples of the Customer Data Form with and without the Pay button:

The following images show examples of the Card Form with and without the Pay button:

If you hide the Pay button, you need to start the one-time token creation through your code. To create the one-time token and continue the payment in your backend, call the submitOneTimeTokenForm
function:
yuno.submitOneTimeTokenForm();
Optional initialization options
parameter
options
parameterThis optional feature is intended for advanced use cases where you need to customize how device identification is handled via cookies.
Starting from Yuno SDK v1.2, the Yuno.initialize
function supports a new optional parameter called options
. This allows for advanced configuration such as customizing the cookie name used for device identification.
Initialization options
The updated function signature is:
const yuno = await Yuno.initialize(publicApiKey, applicationSession, options);
publicApiKey
(string
): Your public API key.applicationSession
(string | undefined
): Optional session ID.Recommendation: Leave this as
undefined
so the SDK can generate and manage its own session internally. Only set this if you require a custom session management strategy.options
(object | undefined
): Optional object for advanced configuration.
Options structure
The options
object supports the following structure:
const options = {
cookies: {
deviceId: {
name: "customCookieName",
},
},
};
If
deviceId.name
is not specified, the SDK defaults to"yuno"
as the cookie name.
Implementation example
const publicApiKey = "your-public-api-key";
const options = {
cookies: {
deviceId: {
name: "custom-device-id",
},
},
};
const yuno = await Yuno.initialize(publicApiKey, undefined, options);
What's next?
Learn about the additional configurations from the Full SDK by accessing Complementary Features. You can also access other functions available on the Yuno Web SDK:
- SDK Customizations: Change the SDK appearance to match your brand
- Payment Status: Update the user about the payment process
- 3DS Setup SDK: Integrate 3DS into your payment flow
Related Links
Find more information and version history for the Web SDK below:
- Web SDK v1.3: The latest version with improved UI grouping and multilingual support.
- Web SDK v1.2: Updated
continuePayment
method and optional initialization parameters.
Updated 18 minutes ago