Secure Fields (Payment)

Implement Yuno's Secure Fields checkout in your application by following these steps.

Yuno provides a TypeScript library for all available methods.

Step 1: Include the library in your project

Before proceeding with the Secure Fields implementation, see the SDK Integration Overview for detailed instructions on how to properly integrate the SDK into your project.

The integration guide provides three flexible methods:

1. Direct HTML script inclusion
2. Dynamic JavaScript injection
3. NPM module installation

After integrating the SDK, continue with the remaining steps on this page.

Step 2: Initialize secure fields with the public key

In your JavaScript application, create an instance of the Yuno class by providing a valid PUBLIC_API_KEY:

const yuno = await Yuno.initialize(PUBLIC_API_KEY);

See the credentials page for more information.

Step 3: Start the checkout process

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.

Parameters

Configure the secure fields with the following options:

const secureFields = yuno.secureFields({
  countrycode: country,
  checkoutSession,
  installmentEnable: false
});

Payments can be customer-initiated (CIT) or merchant-initiated (MIT). See Stored credentials. These steps cover customer-initiated transactions (one-time; no recurrence).

Step 4: Mount the Secure Fields

After defining the parameters, define, configure, and mount the Secure Fields. For each field, set name and options in secureFields.create.

Configurations:

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-*]).

Example (three Secure Fields):

Data available in onChange callback

When the onChange callback is triggered, the data parameter contains:

• Card IIN Information: Card issuer details including scheme, brand, type, and issuer information
• Installment Plans: Available installment options for the account if configured
• Loading States: isCardIINLoading and isInstallmentLoading boolean flags

const secureNumber = secureFields.create({
    name: 'pan',
    options: {
      placeholder: '0000 0000 0000 0000',
      styles: ``,
      label: 'Card Number',
      showError: true,
      errorMessage: "Custom Error",
      validateOnBlur: false,
      onChange: ({ error,data }) => {
        if (error) {
          console.log('error_pan')
        } else {
          console.log('not_error_pan')
        }
      },
      onBlur() {
        console.log('blur_pan')
      },
      onFocus: () => {
        console.log('focus_pan')
      },
      onRenderedSecureField: ()=> {
        console.log('render completed')
      }
    },
  })

  secureNumber.render('#pan')

  const secureExpiration = secureFields.create({
    name: 'expiration',
    options: {
      placeholder: 'MM / YY',
      styles: ``,
      label: 'Card Expiration',
      showError: true,
      errorMessage: "Custom Error",
      onChange: ({ error }) => {
        if (error) {
          console.log('error_expiration')
        } else {
          console.log('not_error_expiration')
        }
      },
      onBlur() {
        console.log('blur_expiration')
      },
      onFocus: () => {
        console.log('focus_expiration')
      },
      onRenderedSecureField: ()=> {
        console.log('render completed')
      }
    },
  })

  secureExpiration.render('#expiration')


  const secureCvv = secureFields.create({
    name: 'cvv',
    options: {
      placeholder: 'CVV',
      styles: ``,
      label: 'CVV',
      showError: true,
      errorMessage: "Custom Error",
      onChange: ({ error }) => {
        if (error) {
          console.log('error_cvv')
        } else {
          console.log('not_error_cvv')
        }
      },
      onBlur() {
        console.log('blur_cvv')
      },
      onFocus: () => {
        console.log('focus_cvv')
      },
      onRenderedSecureField: ()=> {
        console.log('render completed')
      }
    },
  })

  secureCvv.render('#cvv')

Below, you can see a GIF showing how you can configure the Secure Fields:

Step 5: Generate an OTT (one-time token)

With all user information in hand, start the payment by creating a One-Time Token (OTT) using the function secureFields.generateToken. As it is an asynchronous function, use try/catch to handle triggered errors. When you use a vaulted token with the SDK, all the fraud information from the providers you configured in your card routing is collected and attached to the one-time token; you can add installment information and a security code if the provider requires it.

Generate token parameters

const oneTimeToken = await secureFields.generateToken({
  checkoutSession: '{{the checkout session id}}',
  cardHolderName: 'John Deer',
  saveCard: true,
  vaultedToken: "aad8578e-ac2f-40a0-8065-25b5957f6555",
  installment: {
            id: string,
            value: number,
            amount: {
                currency: string,
                value: string,
                total_value: string,
            },
        },
  customer: {
    document: {
      document_number: '1090209924',
      document_type: 'CC',
    },
  },
  cardType: 'DEBIT'
})

You can also use secureFields.generateTokenWithInformation to receive any additional info the customer gives at checkout, such as installments or document type/number. Create a one-time token with error handling:

const oneTimeTokenWithInformation = await secureFields.generateTokenWithInformation({ 
  checkoutSession: '{{the checkout session id}}',
  cardHolderName: 'John Deer',
  saveCard: true,
  vaultedToken: "aad8578e-ac2f-40a0-8065-25b5957f6555",
  installment: {
            id: string,
            value: number,
            amount: {
                currency: string,
                value: string,
                total_value: string,
            },
        },
  customer: {
    document: {
      document_number: '1090209924',
      document_type: 'CC',
    },
  },
  cardType: 'DEBIT'
})

Step 6: Create the Payment

After receiving the one-time token, you can create the payment using one of the following options:

• Create the payment using the Create Payment endpoint.
• Use the createPayment function.

Both options require you to provide the oneTimeToken and the checkoutSession. As creating the payment may raise errors, Yuno recommends you use a try/catch function here.

Check payment status with yuno.mountStatusPayment. Example (createPayment and mountStatusPayment):

Payment creation flow

1. Create Payment: Use the createPayment function with the one-time token and checkout session
2. Check SDK Action: If sdk_action_required is true, call yuno.continuePayment() for additional customer actions
3. Mount Status: If no SDK action is required, use yuno.mountStatusPayment() to display payment status

Mount status payment parameters

const payment = await createPayment({ oneTimeToken, checkoutSession })

if (payment.checkout.sdk_action_required) {
      yuno.continuePayment()
} else {
  yuno.mountStatusPayment({
    checkoutSession: checkoutSession,
    countrycode: 'US',
    language: 'en',
    yunoPaymentResult(data) {
      console.log('yunoPaymentResult', data)
    },
  })
}

Complementary features

For styling, themes, form options, and additional configurations, see SDK customizations.