Book a Demo

Secure Fields (Enrollment)

Suggest Edits

Below, we outline the step-by-step process to enable the Secure Fields Enrollment functionalities in your system:

Step 1: Include the library in your project.

To use enrollment with secure fields you should include our SDK file in your page before close your <body> tag

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

Step 2: Initialize secure fields with the public key

Get a Yuno instance class in your JS app with a valid PUBLIC_API_KEY

const yuno = Yuno.initialize(PUBLIC_API_KEY)

Step 3: Start the checkout process

To do it, use the secureFields function and provide the necessary configuration parameters.

The essential parameters are the countryCode, which determines the country for which the payment process is configured, and checkoutSession, which refers to the current payment's checkout session. The next code block presents an example of the parameter configuration.

The following table lists all required parameters and their descriptions.

ParameterDescription
countryCodeThis parameter determines the country for which the payment process is being configured. It should be set to one of the following country codes: CO, BR, CL, PE, EC, UR, or MX.
checkoutSessionRefers to the current payment's checkout session.
Example: '438413b7-4921-41e4-b8f3-28a5a0141638'
  const secureFields = yuno.secureFields({
    /**
     * country can be one of CO, BR, CL, PE, EC, UR, MX
     */
    countryCode,
    checkoutSession,
  })

Step 4: Mount the Secure Fields

After defining the parameters, you will define, configure, and mount the Secure Fields. For each Secure Field, you need to define the name and options when creating it with the secureFields.create function.

The table below presents all configurations available:

ParametersDescription
nameThe available names for field names are cvv, pan, or expiration.
options.placeholderDefault placeholder for the field.
options.stylesAdditional CSS styles for the current field.
options.labelField visible label.
options.showErrorDefines if errors will be shown. Available options are true and false.
options.onChangeAn auxiliary function that can be configured and will run when the field content changes. Indicates if the fields have errors.
options.onBlurAn auxiliary function that can be configured and will run when blurring from the input.
options.onFocusAn auxiliary function that can be configured and will run when focussing on the input.

Once you have set the parameter, you will render the created Secure Field with the render function by selecting an HTML element using a valid CSS selector (#, ., [data-*]).

The next code block presents an example of the parameter configuration for three Secure Fields, and as they are mounted, the fields are presented to the user.

  const secureNumber = secureFields.create({
    /**
     * Fields name, can be 'cvv' | 'pan' | 'expiration'
     */
    name: 'pan',
    // All options are optional
    options: {
      placeholder: '0000 0000 0000 0000',
      /**
       * you can edit card form styles
       * only you should write css then it will be injected into the iframe
       * example 
       * `@import url('https://fonts.googleapis.com/css2?family=Luckiest+Guy&display=swap');
       *  .Yuno-text-field__content.focus label.Yuno-text-field__label {
       *    color: red;
       *    font-family: 'Luckiest Guy' !important;
       *   }`
       */
      styles: ``,
      label: 'Card Number',
      showError: true,
      // Indicates if the fields has error
      onChange: ({ error }) => {
        if (error) {
          console.log('error_pan')
        } else {
          console.log('not_error_pan')
        }
      },
      // Trigger when blurring from input
      onBlur() {
        console.log('blur_pan')
      },
      // Trigger when focussing on input
      onFocus: () => {
        console.log('focus_pan')
      }
    },
  })

  // Render into desired element
  secureNumber.render('#pan')

  const secureExpiration = secureFields.create({
    /**
     * Fields name, can be 'cvv' | 'pan' | 'expiration'
     */
    name: 'expiration',
    // All options are optional
    options: {
      placeholder: 'MM / YY',
      /**
       * you can edit card form styles
       * only you should write css then it will be injected into the iframe
       * example 
       * `@import url('https://fonts.googleapis.com/css2?family=Luckiest+Guy&display=swap');
       *  .Yuno-text-field__content.focus label.Yuno-text-field__label {
       *    color: red;
       *    font-family: 'Luckiest Guy' !important;
       *   }`
       */
      styles: ``,
      label: 'Card Expiration',
      showError: true,
      // Indicates if the fields has error
      onChange: ({ error }) => {
        if (error) {
          console.log('error_expiration')
        } else {
          console.log('not_error_expiration')
        }
      },
      // Trigger when blurring from input
      onBlur() {
        console.log('blur_expiration')
      },
      // Trigger when focussing on input
      onFocus: () => {
        console.log('focus_expiration')
      }
    },
  })

  // Render into desired element
  secureExpiration.render('#expiration')


  const secureCvv = secureFields.create({
    /**
     * Fields name, can be 'cvv' | 'pan' | 'expiration'
     */
    name: 'cvv',
    // All options are optional
    options: {
      placeholder: 'CVV',
      /**
       * you can edit card form styles
       * only you should write css then it will be injected into the iframe
       * example 
       * `@import url('https://fonts.googleapis.com/css2?family=Luckiest+Guy&display=swap');
       *  .Yuno-text-field__content.focus label.Yuno-text-field__label {
       *    color: red;
       *    font-family: 'Luckiest Guy' !important;
       *   }`
       */
      styles: ``,
      label: 'CVV',
      showError: true,
      // Indicates if the fields has error
      onChange: ({ error }) => {
        if (error) {
          console.log('error_cvv')
        } else {
          console.log('not_error_cvv')
        }
      },
      // Trigger when blurring from input
      onBlur() {
        console.log('blur_cvv')
      },
      // Trigger when focussing on input
      onFocus: () => {
        console.log('focus_cvv')
      }
    },
  })

  // Render into desired element
  secureCvv.render('#cvv')

After they are mounted, the three secure fields will be shown.

Step 5: Create Vaulted Token

To enroll, create a Vaulted Token

// Create Vaulted Token
// This will trigger an error if there are missing data
// You can catch it using a try/catch
const vaultedToken = await secureFields.generateVaultedToken({
  // Required: You can create an input to get this formation
  cardHolderName: 'John Deer',
  // Check your card processor to know if you need to send 
  // customer information
  // full object here https://docs.y.uno/reference/the-customer-object
  customer: {
    document: {
      document_number: '1090209924',
      document_type: 'CC',
    },
  },
})

If you need the full response you can usesecureFields.generateVaultedTokenWithInformation

/**
 *  Create One Time Token
 *  This will trigger an error if there are missing data
 *  You can catch it using a try/catch
 *  Returns an object with the full response
 *  {
 *   code: string;
 *   idempotency_key: string;
 *   organization_code: string;
 *   account_code: string;
 *   customer_session: string;
 *   name: string;
 *   description: string;
 *   status: Enrollment.Status;
 *   type: Payment.Type;
 *   category: Payment.Category;
 *   provider: {
 *       type: string;
 *       action: string;
 *       token: string;
 *       enrollment_id: string | null;
 *       provider_status: string | null;
 *       redirect: string | null;
 *       raw_response: unknown;
 *   };
 *   created_at: Date;
 *   updated_at: Date;
 *  }
 */ 
const vaultedTokenWithInformation = await secureFields.generateVaultedTokenWithInformation({
  // Required: You can create an input to get this formation
  cardHolderName: 'John Deer',
  // Check your card processor to know if you need to send 
  // customer information
  // full object here https://docs.y.uno/reference/the-customer-object
  customer: {
    document: {
      document_number: '1090209924',
      document_type: 'CC',
    },
  },
})

Additional steps

In addition to the code examples provided, you can access the Demo App for a complete implementation of Yuno Secure Fields or go directly to the HTML and JavaScript Secure Fields checkout demos available on GitHub.

Updated 8 months ago