Campos seguros (Pago)

Siga esta guía paso a paso para implementar y habilitar las funcionalidades de pago de Secure Fields de Yuno en tu aplicación.

Paso 1: Incluya la biblioteca en tu proyecto

Antes de proceder a la implementación de los Campos seguros, consulta la Descripción general de la integración del SDK para obtener instrucciones detalladas sobre cómo integrar correctamente el SDK en tu proyecto.

La guía de integración ofrece tres métodos flexibles:

1. Inclusión directa de secuencias de comandos HTML
2. Inyección dinámica de JavaScript
3. Instalación del módulo NPM

Elija el método de integración que mejor se adapte a su flujo de trabajo de desarrollo y requisitos técnicos. Tras completar la integración del SDK, puede continuar con los siguientes pasos para implementar la funcionalidad de campos seguros.

📘

Biblioteca de TypeScript

Si estás usando TypeScript, Yuno proporciona una librería que puedes usar para ver todos los métodos disponibles en Yuno Web SDK.

Paso 2: Inicialice los campos seguros con la clave pública

En su aplicación JavaScript, cree una instancia del archivo Yuno proporcionando un PUBLIC_API_KEY:

const yuno = await YunoinitializePUBLIC_API_KEY);

📘

Credenciales

Para más información, consulte la página de credenciales: https://docs.y.uno/reference/authentication

Paso 3: Iniciar el proceso de pago

Comenzarás el proceso de pago. Para hacerlo, utiliza el secureFields y proporcionar los parámetros de configuración necesarios:

Los parámetros esenciales son los countrycode, que determina el país para el que está configurado el proceso de pago, y checkoutSessionque se refiere a la sesión de pago actual.

Parámetros

Configura los campos seguros con las siguientes opciones:

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

📘

Transacciones iniciadas por clientes y comerciantes

Los pagos pueden ser iniciados por el cliente (CIT) o por el comerciante (MIT). Encontrará más información sobre sus características en Credenciales almacenadas.

El paso a paso presentado en esta página se refiere a una transacción iniciada por el cliente sin la opción de recurrencia. Normalmente, se utiliza en compras únicas en línea, compras en tiendas, retiros en cajeros automáticos, etc.

Paso 4: Monte los Secure Fields

Después de definir los parámetros, definirá, configurará y montará los Secure Fields. Para cada Secure Field, debe definir el name y options al crearlo con el secureFields.create .

La siguiente tabla muestra todas las configuraciones disponibles:

Una vez que hayas configurado el parámetro, renderizarás el Secure Field creado con el render seleccionando un elemento HTML usando un selector de CSS válido (#, ., [data-*]).

El siguiente bloque de código muestra un ejemplo de la configuración de parámetros para tres Campos Seguros, y a medida que se montan, los campos se presentan al usuario:

Parámetros de campo seguro

Datos disponibles en la llamada de retorno onChange

Cuando el onChange se activa la devolución de llamada data contiene el parámetro:

• Información sobre el IIN de la tarjeta: Datos del emisor de la tarjeta, incluido el esquema, la marca, el tipo y la información del emisor.
• Planes de pago a plazos: Opciones de pago a plazos disponibles para la cuenta si se han configurado.
• Estados de carga: isCardIINLoading y isInstallmentLoading banderas booleanas

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')

A continuación, puede ver un GIF que muestra cómo puede configurar los Campos seguros:

Paso 5: Genera un OTT (token de un solo uso)

Con toda la información del usuario en la mano, puede iniciar el pago. Primero, debe crear un token de un solo uso usando la función secureFields.generateToken. Como es una función asincrónica, puedes usar try/catch para asegurarse de que gestionará correctamente los errores desencadenados. El siguiente ejemplo muestra cómo crear un token de un solo uso utilizando token abovedado información:

📘

Beneficios de usar un token almacenado

Al usar un token almacenado con el SDK, se recopila toda la información de fraude de los proveedores que configuró en el enrutamiento de su tarjeta y se adjunta al token de un solo uso. Además, puede agregar información de pago y un código de seguridad si el proveedor lo requiere.

Generar parámetros de Token

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'
})

También puedes usar secureFields.generateTokenWithInformation para recibir cualquier información adicional que el cliente proporcione al finalizar la compra, como cuotas o tipo/número de documento.

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'
})

Paso 6: Crear el pago

Después de recibir el token de un solo uso, puede crear el pago utilizando una de las siguientes opciones:

• Cree el pago utilizando el endpoint Create Payment .
• Use el endpoint createPayment .

Ambas opciones requieren que usted proporcione la oneTimeToken y el checkoutSession. Como la creación del pago puede generar errores, Yuno recomienda utilizar una función try/catch aquí.

Luego, puede verificar el estado del pago usando la función yuno.mountStatusPayment . El siguiente ejemplo utiliza la función createPayment para crear el pago y el mountStatusPayment para mostrar el estado del pago:

pago Flujo de creación

1. Crear Pago: Utiliza el botón createPayment con el token de un solo uso y la sesión de pago
2. Comprobar acción SDK: Si sdk_action_required es verdadero, llame a yuno.continuePayment() para acciones adicionales de los clientes
3. Estado del montaje: Si no se requiere ninguna acción del SDK, utiliza yuno.mountStatusPayment() para visualizar el estado de pago

Montar Estado pago Parámetros

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)
    },
  })
}

📘

App Demo

Además de los ejemplos de código proporcionados, puedes acceder a la Demo App para una implementación completa de los SDK de Yuno. La demo app incluye ejemplos de trabajo de todos los SDK de Yuno y puede ser clonada desde el repositorio de GitHub.

Características complementarias

Yuno Secure Fields proporciona servicios y configuraciones adicionales que puede utilizar para mejorar la experiencia de los clientes:

• Configurar y utilizar TypeScript
• Conservar la información de la tarjeta de crédito para volver a intentar realizar pagos
• Borrar los valores ingresados ​​en los campos de la tarjeta.
• Enfoque de entrada
• Validación de fuerza
• Establecer mensaje de error personalizado
• Establecer tipo de tarjeta

Configurar y utilizar TypeScript

Para usar TypeScript con el SDK Yuno Secure Fields, comience instalando las definiciones de tipo a través de npm:

npm install @yuno-payments/sdk-web-types

Después de finalizar la instalación, incluya las definiciones de tipo en su configuración de TypeScript. Actualice el tsconfig.json archivo a incluir @yuno-payments/sdk-web-types en la matriz de tipos, como en el siguiente ejemplo:

{
  "compilerOptions": {
    "types": ["@yuno-payments/sdk-web-types"]
  }
}

Con las definiciones de tipo instaladas y configuradas, ahora puedes utilizarlas en tu código. El siguiente bloque de código muestra un ejemplo de cómo initialize Yuno y crear una instancia:

import { YunoInstance } from '@yuno-payments/sdk-web-types/dist/types';

const yunoInstance: YunoInstance = await Yuno.initialize('yourPublicApiKey');

Recuerde reemplazar el yourPublicApiKey con su clave API pública real.

Conservar la información de la tarjeta de crédito para volver a intentar realizar pagos

Si se rechaza una transacción, puede conservar los datos de la tarjeta de crédito para volver a intentar un pago después de que el cliente haya ingresado los datos de la tarjeta de crédito. Para hacer eso, debe seguir los pasos a continuación:

1. Añada el parámetro presentado en el siguiente bloque de código al crear el token de un solo uso en el paso 5. Le permitirá recibir cualquier información adicional que el cliente proporcione durante el proceso de pago, como plazos, tipo de documento o número de documento.

const oneTimeTokenWithInformation = await secureFields.generateTokenWithInformation({ 
  checkoutSession: '{{the checkout session id}}',
})

2. En caso de que la transacción sea rechazada, deberá: i. Crear una nueva sesión de pago. ii. Generar un nuevo token de un solo uso. En la generación de token de un solo uso, envíe la nueva sesión de pago en el campo checkoutSession parámetro.
3. Continúe con el nuevo proceso de pago y el token de un solo uso con el flujo de pago habitual.

Borrar los valores ingresados ​​en los campos de la tarjeta.

Relacionado con la funcionalidad anterior, el comerciante puede configurar para borrar la información ingresada en cualquier campo de la tarjeta. Para lograr esto, es necesario ejecutar el método secureFieldInstance.clearValue()para cada campo que desee borrar o eliminar. El siguiente ejemplo muestra cómo hacerlo:

const secureFieldInstance = secureFields.create({...})
secureFieldInstance.clearValue()

Enfoque de entrada

El comerciante puede centrarse en un insumo particular. Para lograr esto, es necesario ejecutar el método secureFieldInstance.focus()para cada campo en el que desee centrarse. El siguiente bloque de código muestra un ejemplo:

const secureFieldInstance = secureFields.create({...})
secureFieldInstance.focus()

Validación de fuerza

El comerciante puede forzar la validación de una entrada en particular. Para lograr esto, es necesario ejecutar el método secureFieldInstance.validate()para cada campo que desee validar. El siguiente bloque de código muestra un ejemplo:

const secureFieldInstance = secureFields.create({...})
secureFieldInstance.validate()

Establecer mensaje de error personalizado

El comerciante puede definir un mensaje de error personalizado después de una validación de entrada. Para lograr esto, es necesario ejecutar el método secureFieldInstance.setError()para cada campo para el que desee establecer un mensaje de error personalizado. El siguiente bloque de código muestra un ejemplo:

const secureFieldInstance = secureFields.create({...})
secureFieldInstancesetError('Error personalizado')

Establecer tipo de tarjeta

El comerciante puede definir el tipo de tarjeta que utiliza el cliente para el pago. Para lograr esto, necesita ejecutar el método secureFieldInstance.setCardType() y enviar 'DEBITO' o 'CREDITO' para cada escenario. Esto es útil para las tarjetas duales, en las que la misma tarjeta puede utilizarse como crédito o débito, como en Brasil. El siguiente bloque de código muestra un ejemplo:

const secureFieldInstance = secureFields.create({...})
secureFieldInstance.setCardType('CRÉDITO')

¿Qué sigue?

Puede acceder a otras funciones disponibles en el Yuno Web SDK:

• Personalizaciones del SDK: Cambia la apariencia del SDK para que coincida con tu marca.
• Estado delpago : Actualiza al usuario sobre el proceso de pago.

Mantente al día

Visita el registro de cambios para ver las últimas actualizaciones del SDK y el historial de versiones.