Full SDK (Web)

Follow this step-by-step guide to implement and enable Yuno's Full Web SDK functionality in your application.

Step 1: Include the library in your project

After completing the SDK integration, you can proceed with the following steps to implement the full checkout functionality.

Step 2: Initialize SDK with the public key

In your JavaScript application, create an instance of the Yuno class by providing a valid PUBLIC_API_KEY. Check the Get your API credentials guide.

Like the example below, use the initialized class that is attributed to the yunoconstant.

const yuno = await Yuno.initialize(PUBLIC_API_KEY)

Step 3: Start the checkout process

To start the checkout, you'll use the function yuno.startCheckout, providing the necessary parameters.

The following table lists all required parameters and their descriptions. For optional parameters, go to Complementary Features.

yuno.startCheckout({
  checkoutSession: '438413b7-4921-41e4-b8f3-28a5a0141638',
  /**
   * The complete list of country codes is available on https://docs.y.uno/docs/country-coverage-yuno-sdk
  */
  country_code: "FR",
  language: 'fr',
  showLoading: true,
  issuersFormEnable: true,
  showPaymentStatus: true,
	/**
   * Set isCreditCardProcessingOnly as true to process all card transactions are credit
   * isCreditCardProcessingOnly: true | false | undefined
  */
  card: {
    isCreditCardProcessingOnly: true,
  },
  onLoading: (args) => {
    console.log(args);
  },
  /**
   * Notifies when a payment method is selected
   */
  yunoPaymentMethodSelected: () => {
    console.log('Payment method selected');
  },
  /**
   * Returns the payment result after continuePayment
   * @param {string} status - The payment status
   */
  yunoPaymentResult: (status) => {
    console.log('Payment result:', status);
  },
  /**
   * Executes when there are errors
   * @param {string} message - Error message
   * @param {any} data - Additional error data
   */
  yunoError: (message, data) => {
    console.error('Payment error:', message, data);
  },
  async yunoCreatePayment(oneTimeToken) {
  	/**
    * The createPayment function calls the backend to create a payment in Yuno.
    * It uses the following endpoint https://docs.y.uno/reference/create-payment
  	*/
    await createPayment({ oneTimeToken, checkoutSession })
    yuno.continuePayment({ showPaymentStatus: true })
  },
})

Step 4: Mount the SDK

Display the payment methods by using the function yuno.mountCheckout() by selecting an HTML element and using a valid CSS selector (#, ., [data-*])

/**
 * Mount checkout in browser DOM
 */
yuno.mountCheckout()

If you want to set a default payment method, use the following code to mount it:

/**
 * Mount checkout in browser DOM with a payment method selected by default
 * @optional
 */
yuno.mountCheckout({
  /**
   * Optional, only needed if you would like this method type selected by default
   * Can be one of 'PAYPAL' | 'PIX' | 'APPLE_PAY' | 'GOOGLE_PAY' | CARD
   */
  paymentMethodType: PAYMENT_METHOD_TYPE,
  /**
   * Optional
   * Vaulted token related to payment method type
   */
  vaultedToken: VAULTED_TOKEN,
})

Step 5: Initiate the payment process

After the user has selected a payment method remember to call yuno.startPayment() to initiate the payment flow. Below you will find an example where yuno.startPayment() is called when the user clicks on button-pay:

const PayButton = document.querySelector('#button-pay')

PayButton.addEventListener('click', () => {
  yuno.startPayment()
})

Step 6: Get the OTT (one-time token)

Once 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 any additional info given by the customer in the checkout such as installments or document type/number.

yunoCreatePayment(oneTimeToken, tokenWithInformation)

Step 7: Create the Payment

Once the previous steps are complete, you can 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.

continuePayment return value or null

For 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 will return 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, it allows you to handle your application's payment flows that require custom redirect handling. When it returns null, no additional merchant-side action is needed.

Step 8: Get payment status

Call the yunoPaymentResult() function to obtain the payment status. Based on the status, you can show your customer the corresponding screen depending on the final result of the payment.

Step 9: Receive payment result through webhook

Yuno also recommends configuring Webhooks in your dashboard. Webhooks are the best way to ensure your system is up-to-date with payment progress and status. Since the event notifications trigger automatically, your system won't need to perform recurrent requests to Yuno.

Complementary features

Yuno Web SDK provides additional services and configurations you can use to improve customers' experience:

• Form loader
• Render mode
• Card form configurations
  • Save Card for future payments
  • Rendering modes
  • Text payment form buttons
  • Persist credit card form to retry payments
  • Hide Pay button

Form loader

Control the use of the loader.

yuno.startCheckout({
  showLoading: true,
})

Form of the issuer

yuno.startCheckout({
  issuersFormEnable: true,
})

Mode of form rendering

yuno.startCheckout({
  renderMode: {
    /**
     * Type can be one of `modal` or `element`
     * By default the system uses 'modal'
     * It is optional
     */
    type: 'modal',
    /**
     * Element where the form will be rendered.
     * It is optional
     * Can be a string (deprecated) or an object with the following structure:
     * {
     *   apmForm: "#form-element",
     *   actionForm: "#action-form-element"
     * }
     */
    elementSelector: {
      apmForm: "#form-element",
      actionForm: "#action-form-element"
    }
  },
})

Card form configurations

yuno.startCheckout({
  card: {
    type: "extends",
    styles: '',
    cardSaveEnable: false,
    texts: {}
  },
})

Save card for future payments

In addition, you can display a checkbox for saving or enrolling cards using the cardSaveEnable: true. Below are examples of the checkbox for both card form renders.

Rendering modes

Below you find screenshots presenting the difference between the following:

• Render modes modal and elements for the payment method list
• Render modes step and extends for the credit card form

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

Text payment form buttons

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 that, you will need to:

1. Add the following parameter while initializing the SDK to persist the credit card form after the one-time use token is created:
   JavaScript

   yuno.startCheckout({
     automaticallyUnmount: false,
   })
   

2. In case the transaction is rejected, you will need to:
   1. Execute the method yuno.notifyError() to delete the previously entered CVV for the first transaction
   2. Create a new checkout session and update the SDK with the new one by executing yuno.updateCheckoutSession(checkoutsession)
3. 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. To control this feature, you'll set showPayButton to false when starting the checkout with the startCheckout function. The code block below presents an example of how to hide the payment button:

yuno.startCheckout({
  /**
   * Hide (false) or show (true) the customer or card form pay button
   * @default true
   * @optional
   */
  showPayButton: false,
})

The following images present examples of the Customer Data Form with and without the Pay button:

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

If you hide the Pay button, you will 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. The code block below presents how to use the submitOneTimeTokenForm function.

/**
 * This function triggers the same functionality that is called when the customer clicks on the pay form button.  This doesn't work on the step Card form
 */
yuno.submitOneTimeTokenForm()

What's next?

Learn about the additional configurations from the Full SDK 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

Below, we outline the step-by-step process to enable the full Web SDK functionalities in your system:

Step 1: Include the library in your project

Ensure the Yuno SDK file is included in your webpage before closing the <body> tag. Refer to the example below:

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

Step 2: Initialize SDK with the public key

In your JavaScript application, create an instance of the Yuno class by providing a valid PUBLIC_API_KEY. Check the Get your API credentials guide.

Like the example below, use the initialized class that is attributed to the yunoconstant.

const yuno = Yuno.initialize(PUBLIC_API_KEY)

Step 3: Start the checkout process

To start the checkout, you'll use the function yuno.startCheckout, providing the necessary parameters.

The following table lists all required parameters and their descriptions. For optional parameters, go to Complementary Features.

yuno.startCheckout({
  checkoutSession: '438413b7-4921-41e4-b8f3-28a5a0141638',
  /**
   * The complete list of country codes is available on https://docs.y.uno/docs/country-coverage-yuno-sdk
  */
  country_code: "FR",
  language: 'fr',
  showLoading: true,
  issuersFormEnable: true,
  showPaymentStatus: true,
	/**
   * Set isCreditCardProcessingOnly as true to process all card transactions are credit
   * isCreditCardProcessingOnly: true | false | undefined
  */
  card: {
    isCreditCardProcessingOnly: true,
  },
  onLoading: (args) => {
    console.log(args);
  },
  /**
   * Notifies when a payment method is selected
   */
  yunoPaymentMethodSelected: () => {
    console.log('Payment method selected');
  },
  /**
   * Returns the payment result after continuePayment
   * @param {string} status - The payment status
   */
  yunoPaymentResult: (status) => {
    console.log('Payment result:', status);
  },
  /**
   * Executes when there are errors
   * @param {string} message - Error message
   * @param {any} data - Additional error data
   */
  yunoError: (message, data) => {
    console.error('Payment error:', message, data);
  },
  async yunoCreatePayment(oneTimeToken) {
  	/**
    * The createPayment function calls the backend to create a payment in Yuno.
    * It uses the following endpoint https://docs.y.uno/reference/create-payment
  	*/
    await createPayment({ oneTimeToken, checkoutSession })
    yuno.continuePayment({ showPaymentStatus: true })
  },
})

Step 4: Mount the SDK

Display the payment methods by using the function yuno.mountCheckout() by selecting an HTML element and using a valid CSS selector (#, ., [data-*])

/**
 * Mount checkout in browser DOM
 */
yuno.mountCheckout()

If you want to set a default payment method, use the following code to mount it:

/**
 * Mount checkout in browser DOM with a payment method selected by default
 * @optional
 */
yuno.mountCheckout({
  /**
   * Optional, only needed if you would like this method type selected by default
   * Can be one of 'PAYPAL' | 'PIX' | 'APPLE_PAY' | 'GOOGLE_PAY' | CARD
   */
  paymentMethodType: PAYMENT_METHOD_TYPE,
  /**
   * Optional
   * Vaulted token related to payment method type
   */
  vaultedToken: VAULTED_TOKEN,
})

Step 5: Initiate the payment process

After the user has selected a payment method remember to call yuno.startPayment() to initiate the payment flow. Below you will find an example where yuno.startPayment() is called when the user clicks on button-pay:

const PayButton = document.querySelector('#button-pay')

PayButton.addEventListener('click', () => {
  yuno.startPayment()
})

Step 6: Get the OTT (One Time Token)

Once the customer fills out the requested data in Yuno's payment forms, the SDK provides the OTT. The configuration function yuno.CreatePayment(oneTimeToken) is then triggered with the OTT (One Time Token).

 yunoCreatePayment(oneTimeToken)

You can also use tokenWithInformation to receive any additional info given by the customer in the checkout such as installments or document type/number.

yunoCreatePayment(oneTimeToken, tokenWithInformation)

Step 7: Create the Payment

Once you have completed the steps described before, you can create a payment. The back-to-back payment creation must be carried out using the Create Payment endpoint. The merchant should call their backend to create the payment within Yuno, using the OTT (One Time Token) and the checkout session.

What's next?

Learn about the additional configurations from the Full SDK 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.