CulqiJS v4 | Documentación

CulqiJS versión 4

Si quieres brindar una experiencia personalizada de compra a tus clientes, debes usar Culqi JS.

Culqi.JS facilita la integración con Culqi en tu tienda web y móvil. Además, te permite personalizar todo el formulario de pago.

Usos del CulqiJS

Cargo único: Usa CulqiJS para tokenizar los datos de la tarjeta, enviar su ID a tu backend para realizar el cargo único.
Cargo One-click: Usa CulqiJS para tokenizar los datos de la tarjeta, enviar su ID a tu backend, registrar un cliente y generar una tarjeta(card) para poder realizar cargos recurrentes One-click.
Registrar suscripciones: Usa CulqiJS para tokenizar los datos de la tarjeta, enviar su ID a tu backend, registrar a un cliente, generar una tarjeta(card) y una suscripción en base a un plan.
Órdenes de pago: Usa el CulqiJS para realizar pagos a través de PagoEfectivo(banca móvil e internet, agentes y bodegas), billeteras móviles y coutéalo.

Integra CulqiJS en tu tienda virtual

Con CulqiJS puedes personalizar todo el formulario de pago para tokenizar los datos de tarjeta, para integrarlo debes seguir los siguientes pasos:

Desarrolla tu checkout personalizado con CulqiJS
Configurar CulqiJS para tokenizar la tarjeta.
Enviar el ID del objeto token a tu backend.

Paso 1. Desarrolla tu checkout personalizado con CulqiJS

Método de pago con tarjeta

Crea tu formulario de captura de datos de la tarjeta. En este paso, el cliente ingresa la información de su tarjeta para que CulqiJS pueda crear el objeto token usando la función token.generate().

Se deseas habilitar el listado de cuotas o CSI, debes agregar el select objeto “card[installments]” en tu checkout.

<form>
  <div>
    <label>
      <span>Correo Electrónico</span>
      <input type="text" size="50" data-culqi="card[email]" id="card[email]">
    </label>
  </div>
  <div>
    <label>
      <span>Número de tarjeta</span>
      <input type="text" size="20" data-culqi="card[number]" id="card[number]">
    </label>
  </div>
  <div>
    <label>
      <span>CVV</span>
      <input type="text" size="4" data-culqi="card[cvv]" id="card[cvv]">
    </label>
  </div>
  <div>
    <label>
      <span>Fecha expiración (MM/YYYY)</span>
      <input size="2" data-culqi="card[exp_month]" id="card[exp_month]">
      <span>/</span>
      <input size="4" data-culqi="card[exp_year]" id="card[exp_year]">
    </label>
  </div>
  <!--Para habilitar CSI debemos agregar el siguiente select-->
  <div>
	  <label>
		  <span>Cuotas</span>
	  </label>
	  <select disabled id="card[installments]">
		  <option value="1">selecciona...</option>
	  </select>
	</div>
</form>
<button id="btn_pagar">Pagar</button>

Método de pago con yape

Crea tu formulario de captura de datos del número de teléfono y el código de aprobación. En este paso, el cliente ingresa su número telefónico vinculado con yape y el código de aprobación obtenida desde su aplicativo Yape para que CulqiJS pueda crear el objeto token usando la función yape.generate().

<form>
  <div>
    <label>
      <span>Teléfono</span>
      <input type="text" size="9" data-culqi="yape[phone]" id="yape[phone]">
    </label>
  </div>
  <div>
    <label>
      <span>Código</span>
      <input type="text" size="6" data-culqi="yape[code]" id="yape[code]">
    </label>
  </div>
</form>
<button id="btn_pagar">Pagar</button>

Paso 2. Configurar Culqi Checkout para tokenizar la tarjeta

Incluye CulqiJS en tu tienda virtual y configura tu llave pública. Puedes incluirlo antes del cierre de la etiqueta “body”:

<body>
  <script src="https://checkout.culqi.com/js/v4"></script>
  <script>
    Culqi.publicKey = 'Aquí inserta tu llave pública';
  </script>
</body>

Luego, configura (Culqi.settings) los valores a mostrar en el formulario de Culqi Checkout. Para encriptar el payload de los servicios del Culqi JS configura las variables xculqirsaid y rsapublickey.

<script>
  Culqi.settings({
    currency: 'PEN',
    amount: 3500, // Este parámetro es requerido para realizar pagos yape
    order: 'ord_live_0CjjdWhFpEAZlxlz', // Este parámetro es requerido para realizar pagos con pagoEfectivo, billeteras y Cuotéalo
    xculqirsaid: 'Inserta aquí el id de tu llave pública RSA',
    rsapublickey: 'Inserta aquí tu llave pública RSA',
  });
</script>

Luego, configura los métodos de pago (CulqiOptions).

Si colocas el valor true en alguno de estos medios de pagos, se habilitarán en tu checkout. Si no deseas mostrarlos, deberás colocar false.

<script>
  Culqi.options({
      paymentMethods: {
        tarjeta: true,
        bancaMovil: true,
        agente: true,
        billetera: true,
        cuotealo: true,
        yape: true
      }
  });
</script>

Luego, debes llamar a la función Culqi.validationPaymentMethods(). Esta función validará la información ingresada en Culqi.settings y Culqi.options, y retornará la variable Culqi.paymentOptionsAvailable con los métodos de pagos disponibles(available = true si están disponibles o available = false si no están disponibles).

<script>
  Culqi.validationPaymentMethods();
  console.log(Culqi.paymentOptionsAvailable);
</script>

Dependiendo del resultado, se podrá obtener 3 objetos:

“token”: con la función generate() te permitirá generar el token ID para el caso de pagos con tarjetas.
“cip”: para pagos con billeteras móviles y PagoEfectivo(banca móvil e internet, agentes y bodegas), usa la función generate() que te permitirá generar un código “CIP”.
“cuotealo”: con una función generate() que te permitirá generar la url para pagos con Cuotéalo.
”yape”: con una función generate() que te permitirá generar el token ID para el caso de pagos con yape.

A continuación mostramos algunos ejemplos del contenido de paymentOptionsAvailable:

Checkout Culqi success validation

De no pasar la validación, te mostrará que no está habilitado y un mensaje de la posible causa:

Checkout Culqi error validation

A continuación mostramos un ejemplo del uso de la funciones generate().

<script>
  const btn_pagar = document.getElementById("btn_pagar");

  // Validamos los métodos de pago por el cual podras hacer la compra
  Culqi.validationPaymentMethods();
  //Obtenemos los metodos de pagos disponibles
  var paymentTypeAvailable = Culqi.paymentOptionsAvailable;
  btn_pagar.addEventListener("click", function (e) {
    // Crea el objeto Token con Culqi JS
    if (paymentTypeAvailable.token.available) {
      paymentTypeAvailable.token.generate();
    }
    // Crea el objeto Token con Culqi JS
    if (paymentTypeAvailable.yape.available) {
      paymentTypeAvailable.yape.generate();
    }
    // Crea cip
    if (paymentTypeAvailable.cip.available) {
      paymentTypeAvailable.cip.generate();
    }
    // Crea el link de cuotéalo
    if (paymentTypeAvailable.cuotealo.available) {
      paymentTypeAvailable.cuotealo.generate();
    }

    e.preventDefault();
  });
</script>

Paso 3. Enviar el ID del objeto token a tu backend

Luego de haber generado el token, este estará disponible en la función culqi(), tambien estará disponible el paymentCode (código CIP) para los pagos por banca movíl e internet, agentes y bodegas. Tambien estará disponible la url del QR para los pagos con billeteras móviles, y tambien estará disponible la url de Cuotélo para los pagos con este medio.

<script>
  function culqi() {
    if (Culqi.token) {
      // Objeto Token creado exitosamente!
      const token = Culqi.token.id;
      console.log("Se ha creado un Token: ", token);
    } else if (Culqi.order) {
      // Objeto order creado exitosamente!
      const order = Culqi.order;
      console.log("Se ha creado el objeto Order: ", order);
      if (order.paymentCode) {
        console.log("Se ha creado el cip: ", order.paymentCode);
      }
      if (order.qr) {
        console.log("Se ha generado el qr: ", order.qr);
      }
      if (order.cuotealo) {
        console.log("Se ha creado el link cuotéalo: ", order.cuotealo);
      }
    } else {
      // Mostramos JSON de objeto error en consola
      console.log("Error : ", Culqi.error);
    }
  }
</script>