Headless SDK (Pago Web)

👍

SDK recomendado

Recomendamos utilizar el Seamless SDK Web para una integración sin problemas. Esta opción ofrece una solución de pago flexible con componentes de interfaz de usuario predefinidos y opciones de personalización.

El SDK Headless de Yuno te permite crear pagos. Ten en cuenta que, al usarlo, deberás solicitar y enviar por API todos los campos obligatorios que el proveedor de pagos requiere para generar el pago en su API.

El SDK Headless de Yuno le permite crear pagos en dos escenarios diferentes:

• Cree un Token de un solo uso utilizando la información de la tarjeta de crédito y, a continuación, cree un pago.
• Cree un Token de un solo uso usando un vaulted_token desde una tarjeta de crédito previamente registrada y luego crear un pago.

Los siguientes pasos describen la creación de un pago usando el Headless SDK de Yuno.

Paso 1: Incluya la biblioteca en tu proyecto

Antes de proceder a la implementación Headless SDK , consulta la Visió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 pago sin interfaz gráfica.

📘

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 el SDK Headless 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

A continuación, iniciará el proceso de pago utilizando la función apiClientPayment proporcionando los parámetros de configuración necesarios.

Parámetros

Configura el pago con las siguientes opciones:

const apiClientPayment = yuno.apiClientPayment({
  country_code: "US",
  checkout_session: "eec6578e-ac2f-40a0-8065-25b5957f6dd3"
});

Paso 4: Generar token

Tras recopilar toda la información del usuario, puede iniciar el pago. Primero, debe crear un token de un solo uso (OTT) mediante la función apiClientpayment.generateToken. Como es una función asincrónica, puedes usar try/catch para asegurarse de que gestionará correctamente los errores desencadenados. Los siguientes ejemplos muestran diferentes escenarios para crear el token de un solo uso:

1. Ejemplo 1: Crear un token de un solo uso utilizando una tarjeta como método de pago e incluyendo toda la información necesaria de la tarjeta.
2. Ejemplo 2:Crea un token de un solo uso usando el vaulted_token .

📘

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.

const oneTimeToken = await apiClientPayment.generateToken({
  checkout_session: "eec6578e-ac2f-40a0-8065-25b5957f6dd3",
  payment_method: {
    type: "CARD",
    vaulted_token: null,
    card: {
      save: false,
      detail: {
        expiration_month: 11,
        expiration_year: 25,
        number: "4111111111111111",
        security_code: "123",
        holder_name: "ANDREA B",
        type: "DEBIT"
      },
      installment: {
        id: "64ceacef-0886-4c81-9779-b2b3029c4e8b",
        value: 1
      }
    },
    customer: {},
    device_fingerprint: "0753b47f-bb43-86ab-647b-d735b67baac6",
    third_party_session_id: "QbJU2KolVUm1fhQR0s9qgrS0ArEQmEfE"
  }
});

Parámetros del ejemplo 1

const oneTimeToken = await apiClientPayment.generateToken({
  checkout_session: "eec6578e-ac2f-40a0-8065-25b5957f6dd3",
  payment_method: {
    type: "CARD",
    vaulted_token: "aad8578e-ac2f-40a0-8065-25b5957f6555",
    card: {
      detail: {
        security_code: "123"
      },
      installment: {
        id: "64ceacef-0886-4c81-9779-b2b3029c4e8b",
        value: 1
      }
    }
  }
});

Parámetros del ejemplo 2

El siguiente bloque de código muestra el apiClientPayment.generateToken para los dos ejemplos anteriores:

{
  "token": "ee78bc2a-63b4-45bb-bd28-3e6829ab1c3d",
  "vaulted_token": null,
  "vault_on_success": false,
  "type": "CARD",
  "card_data": {
    "holder_name": "ANDREA B",
    "iin": "41111111",
    "lfd": "1111",
    "number_length": 16,
    "security_code_length": 3,
    "brand": "VISA",
    "type": "CREDIT",
    "category": "CREDIT",
    "issuer_name": "JPMORGAN CHASE BANK N A",
    "issuer_code": null
  },
  "customer": {
    "first_name": "Cesar",
    "last_name": "Sanchez",
    "email": "[email protected]",
    "gender": "",
    "phone": null,
    "billing_address": null,
    "document": null,
    "browser_info": {
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36",
      "accept_header": "*/*",
      "accept_content": "*/*",
      "accept_browser": "*/*",
      "color_depth": "24",
      "screen_height": "1080",
      "screen_width": "2560",
      "javascript_enabled": true,
      "java_enabled": false,
      "browser_time_difference": "300",
      "language": "en-US"
    },
    "device_fingerprint": "19764508-c9df-a90b-a365-83b2d718c12e"
  },
  "installment": null,
  "country": "CO"
}

{
  token: 'ee78bc2a-63b4-45bb-bd28-3e6829ab1c3d',
  vaulted_token: aad8578e-ac2f-40a0-8065-25b5957f6555,
  vault_on_success: false,
  type: 'CARD',
  card_data: {
    holder_name: 'ANDREA B',
    iin: '41111111',
    lfd: '1111',
    number_length: 16,
    security_code_length: 3,
    brand: 'VISA',
    type: 'CREDIT',
    category: 'CREDIT',
    issuer_name: 'JPMORGAN CHASE BANK N A',
    issuer_code: null,
  },
  customer: {
    first_name: 'Cesar',
    last_name: 'Sanchez',
    email: '[email protected]',
    gender: '',
    phone: null,
    billing_address: null,
    document: null,
    browser_info: {
      user_agent:
        'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36',
      accept_header: '*/*',
      accept_content: '*/*',
      accept_browser: '*/*',
      color_depth: '24',
      screen_height: '1080',
      screen_width: '2560',
      javascript_enabled: true,
      java_enabled: false,
      browser_time_difference: '300',
      language: 'en-US',
    },
    device_fingerprint: '19764508-c9df-a90b-a365-83b2d718c12e',
  },
  installment: null,
  country: 'CO',
}

Paso 5: Crear el pago

Después de recibir el token único, puede crear el pago utilizando el endpoint de Crear pago Para obtener el resultado del pago final, informará el token único recibido en Paso 4 a través del pedido payment_method.token parámetro. El siguiente bloque de código muestra un ejemplo de pedido para crear un pago:

{
  "merchant_order_id": "0000022",
  "country": "US",
  "account_id": "<Your account_id>",
  "description": "Test",
  "amount": {
    "currency": "USD",
    "value": 500
  },
  "customer_payer": {
    "id": "cfae0941-7234-427a-a739-ef4fce966c79"
  },
  "checkout": {
    "session": "<checkout session>"
  },
  "workflow": "SDK_CHECKOUT",
  "payment_method": {
    "type": "CARD",
    "token": "2cd31999-e44e-4de3-bbe4-179981ff4295"
  }
}

La respuesta del endpoint proporciona el parámetro sdk_action_required que define si son necesarias acciones adicionales para concluir el pago:

• Si su cliente selecciona un método de pago sincrónico, el pago se completa al instante. En este escenario, el campo sdk_action_required en la respuesta de la API será false, y el proceso de pago concluye en este paso.
• Cuando se necesita una interacción adicional del SDK para completar el flujo de pago, sdk_action_required será true. Si este es el caso, debes seguir las instrucciones del Paso 6.

Paso 6: Obtén la URL del desafío 3DS

Como se describe en la página Verificación de tarjeta 3DS, un pago con 3DS puede requerir una impugnación adicional para comprobar la identidad del cliente. Si es necesario un paso de verificación adicional relacionado con una impugnación de verificación 3DS, la respuesta al endpoint Crear pago tendrá la siguiente información:

• Un tipo de transacción THREE_D_SECURE .
• Estado igual a PENDING y subestado igual a WAITING_ADDITIONAL_STEP.
• El objeto sdk_action_required establecida como true.

Para obtener la URL del desafío 3DS, debes llamar al getThreeDSecureChallenge proporcionando la función checkoutSession utilizado para crear el pago.

const data = await apiClientPayment.getThreeDSecureChallenge(checkoutSession?: string): Promise<{url: string}>

Si la tarjeta no requiere un desafío para verificar la identidad del cliente, la url volverá null.

En un navegador web, puedes abrir la URL en una nueva pestaña o en un IFrame. Para abrir la URL en un iframe, debes configurar el parámetro embedded = true. En caso contrario, puedes omitir este parámetro, cuyo valor predeterminado es false. El siguiente bloque de código muestra un ejemplo de visualización del contenido del desafío 3DS en un IFrame:

document.querySelector('#element').innerHTML = `
   <iframe
     src="${data.url}&embedded=true"
     height="700px"
     width="100%"
     border="0"
     frameBorder="0">
   </iframe>
 `;

window.addEventListener('message', (event) => {
   if (
        !event.origin.toLocaleLowerCase().includes('sdk-3ds') ||
        event?.data?.origin !== 'CHALLENGE'
   ) {
     return
   }
   document.querySelector('#element').innerHTML = '';
   if (event.data.status === 'ERROR') {
     document.querySelector('#element').innerHTML = 'There was an error';
   } else {
     document.querySelector('#element').innerHTML = 'Challenge was finished';
   }
});

Tu eres responsable de redirigir a tus clientes a la URL proporcionada por el redirect_url para completar el desafío. Una vez que el cliente complete con éxito el desafío 3DS, será redirigido automáticamente al callback_url, que proporcionó al crear el checkout_session con el endpoint Crear Sesión de Checkout endpoint.

Para completar el flujo de pago de Headless SDK , necesita utilizar Yuno Webhooks, que le notificará puntualmente sobre el resultado del desafío 3DS y el estado final de pago. El uso de webhooks garantiza que reciba actualizaciones en tiempo real sobre el progreso de la transacción de pago. Además de los webhooks, puede recuperar la información de pago utilizando el endpoint Recuperar pago por ID.

Paso 7: Obtener acciones de pago

A veces el pago puede requerir una acción adicional para continuar el flujo de pago. Para determinar qué acción es necesaria, debe llamar a la función getContinuePaymentAction proporcionando el método checkoutSession utilizado para crear el pago.

const data = await apiClientPayment.getContinuePaymentAction({ checkoutSession: string }): Promise<ContinuePaymentAction>

El objeto getContinuePaymentAction devuelve un ContinuePaymentAction que describe la acción específica requerida para continuar el flujo de pago, dependiendo del proveedor y del paso específico requerido.

ContinuePaymentAction estructura de respuesta

La respuesta contiene información sobre el tipo de acción requerida y los datos necesarios para llevarla a cabo:

type ContinuePaymentAction = {
  type: Provider.Type;
  action: Provider.Action;
  payment_code?: {
    code: string;
    reference: string;
    expiration_time?: number;
  };
  image?: {
    type: string;
    value: string;
    reference: string;
    expiration_time?: number;
    additional_data?: Record<string, undefined>;
  };
  redirect?: {
    init_url: string;
    success_url: string;
    error_url: string;
  };
  otp?: {
    length: number;
    expiration_time: number;
    retries: {
      accepts: boolean;
      number: number;
    };
    resend: {
      timer: number;
      number: number;
    };
    payment_instructions: string;
  };
  three_d_secure_redirect?: {
    init_url: string;
    access_token: string;
    redirect_url?: string;
  };
  transaction_id?: string;
  request_html?: {
    body?: Record<string, string>;
    headers?: Record<string, string>;
    method?: "POST" | "GET" | "PUT" | "PATCH" | "DELETE";
    url: string;
  };
  sdk_provider?: {
    client_id?: string;
    intent?: string;
    components?: string;
    gateway: string;
    init_url?: string;
    merchant_id: string;
    amount: {
      currency: string;
      value: number;
    };
    protocol_version?: string;
    provider_id?: string;
    payment_methods?: string[];
    supported_networks?: string[];
    session?: {
      epoch_timestamp: number;
      expires_at: number;
      merchant_session_identifier: string;
      nonce: string;
      merchant_identifier: string;
      domain_name: string;
      display_name: string;
      signature: string;
      operational_analytics_identifier: string;
      retries: number;
      psp_id: string;
    };
    provider_token_id?: string;
  };
  render_html?: {
    content?: string;
    redirect_url?: string;
  };
  info?: {
    screen_info?: string;
  };
  render_iframe: {
    init_url: string;
    access_token: string;
    redirect_url?: string;
  };
};

ContinuePaymentAction Campos

Tipos de proveedores y acciones

Los siguientes enums definen los proveedores de pago soportados y las posibles acciones:

export declare namespace Proveedor {
  enum Tipo {
    MERCADO_PAGO = "MERCADO_PAGO",
    WOMPI = "WOMPI",
    PAYMENTEZ = "PAYMENTEZ",
    GETNET = "GETNET",
    TRANSFEERA = "TRANSFEERA",
    CYBERSOURCE_3DS = "CYBERSOURCE_3DS",
    NETCETERA_3DS = "NETCETERA_3DS",
    XENDIT_3DS = "XENDIT_3DS",
    DLOCAL = "DLOCAL",
    CIELO = "CIELO",
    INSWITCH = "INSWITCH",
    PAGALEVE = "PAGALEVE",
    UNLIMINT_3DS = "UNLIMINT_3DS"
  }

  enum Acción {
   pago=pago",
    IMAGE = "IMAGEN",
    REDIRECT_URL = "REDIRECT_URL",
    FORM = "FORM",
    INFO = "INFO",
    OTP = "OTP",
    SDK_PROVIDER = "SDK_PROVIDER",
    THREE_D_SECURE_REDIRECT_URL = "THREE_D_SECURE_REDIRECT_URL",
   pedido=pedido",
    RENDER_HTML = "RENDER_HTML",
    RENDER_IFRAME = "RENDER_IFRAME"
  }
}

Tipos de proveedores y acciones

Gestión de diferentes tipos de acciones

Basado en el action en la respuesta, deberá gestionar cada tipo de acción en consecuencia:

REDIRECT_URL Acción

Cuando la acción es REDIRECT_URLdebe redirigir al usuario a la URL proporcionada en data.redirect.init_url:

if (data.action === "REDIRECT_URL") {
  window.location.href = data.redirect.init_url;
}

Otros tipos de acción

Cada tipo de acción requiere un tratamiento específico en función de los datos facilitados:

• pago: Muestra el código de pago y la referencia al usuario
• IMAGEN: Mostrar un código QR u otra imagen al usuario.
• OTP: Presentar un formulario de introducción de OTP al usuario
• SDK_PROVIDER: Initialize el SDK del proveedor específico
• RENDER_IFRAME: Mostrar un iframe con la interfaz del proveedor.

📘

pago Gestión de acciones

La implementación específica para manejar cada tipo de acción dependerá del marco de trabajo y los requisitos de la interfaz de usuario de tu aplicación. Asegúrate de que manejas todos los tipos de acción posibles que tus proveedores de pago configurados podrían devolver.

📘

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.

Mantente al día

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