SDK JavaScript

SDK 2.1.1

Qué es#

Los campos de tarjeta viven en tu página. El SDK V2 toma control de esos inputs y manda los datos del navegador directo a Tilopay: no pasan por tu servidor.

Para quién es#

Para equipos que quieren controlar el diseño del checkout sin que los datos de tarjeta toquen su backend. Necesitás frontend con JavaScript y un backend mínimo para obtener el token del SDK.

Cómo se arma, en orden#

Credenciales. No hay credenciales de sandbox compartidas: obtené las tuyas en registro de developer.
Token del SDK. Tu backend lo pide con POST /api/v1/loginSdk. Ver autenticación.
Cargá el script. Ver instalación.
Poné los inputs con los ids del contrato y el contenedor responseTilopay. Ver campos del formulario.
Iniciá la compra con Tilopay.Init() y mostrale al cliente los métodos de pago que devuelve.
Cerrá la compra con Tilopay.startPayment(). El SDK maneja 3DS y renderiza el resultado en tu URL de redirect.
Confirmá el resultado en tu servidor. El redirect es del cliente; antes de entregar el producto, confirmá el estado con el API. Ver confirmar el resultado.

Flujo de métodos#

SINPE Móvil: confirmación y plazo#

Cuando llega la transferencia, el SDK redirige a tu redirect; si enviaste webhook, Tilopay también lo notifica. El SDK no fija un plazo, pero Tilopay asocia transferencias con órdenes SINPE Móvil creadas en los últimos 25 minutos: el cliente debe transferir dentro de ese plazo. La sesión depende de la vigencia del token del SDK.

Requerido:   Init()  ──────────────────────────────►  startPayment()
Opcionales:          getCardType()   (mostrar el ícono de la marca)
                     updateOptions() (si cambian datos)

También podés aceptar Apple Pay: el SDK dibuja el botón dentro del formulario.

Confirmá el resultado en tu servidor#

Al finalizar, el navegador del cliente llega a tu URL de redirect con los parámetros del resultado: code, description, auth, order, tpt, tilopay-transaction, OrderHash y returnData. Ver la tabla completa en parámetros que llegan al redirect.

code = 1 significa transacción aprobada; cualquier otro valor es un rechazo.
El redirect lo recibe el navegador del cliente, así que no es prueba suficiente: antes de entregar el producto, confirmá el estado con POST /api/v1/consult desde tu servidor.
OrderHash es un string único por transacción: su algoritmo no es público y se solicita escribiendo a soporte@tilopay.com.

Antes de asumir que estás en pruebas#

Pruebas y producción comparten host: el modo se verifica con el campo environment de Init() ("TEST" o "PROD"). Ver entornos.

Ejemplo completo#

Formulario dentro de .payFormTilopay, los cinco campos, botones Pagar y Actualizar, responseTilopay fuera del formulario, el script v2, Init() con todos los campos, la carga de methods y cards en sus select y startPayment().

<div class="payFormTilopay">
  <select id="tlpy_payment_method" name="tlpy_payment_method"></select>
  <select id="tlpy_saved_cards" name="tlpy_saved_cards"></select>
  <input type="text" id="tlpy_cc_number" name="tlpy_cc_number" />
  <input type="text" id="tlpy_cc_expiration_date" name="tlpy_cc_expiration_date" placeholder="12/30" />
  <input type="text" id="tlpy_cvv" name="tlpy_cvv" />
  <button type="button" id="pagar">Pagar</button>
  <button type="button" id="actualizar">Actualizar</button>
</div>

<div id="responseTilopay"></div>

<script src="https://app.tilopay.com/sdk/v2/sdk_tpay.min.js"></script>
<script>
  async function iniciar() {
    const init = await Tilopay.Init({
      token: "<token_del_sdk>",
      currency: "CRC",
      language: "es",
      amount: 100.0,
      billToEmail: "cliente@ejemplo.com",
      orderNumber: "ORD-2026-000123",
      typeDni: 1,
      dni: "0707770777",
      billToFirstName: "Ana",
      billToLastName: "Rojas",
      billToAddress: "Avenida 1, Local 2",
      billToAddress2: "",
      billToCity: "San José",
      billToState: "SJ",
      billToZipPostCode: "10101",
      billToCountry: "CR",
      billToTelephone: "88888888",
      shipToFirstName: "Ana",
      shipToLastName: "Rojas",
      shipToAddress: "Avenida 1, Local 2",
      shipToAddress2: "",
      shipToCity: "San José",
      shipToState: "SJ",
      shipToZipPostCode: "10101",
      shipToCountry: "CR",
      shipToTelephone: "88888888",
      capture: 1,
      redirect: "https://ejemplo.com/respuesta",
      subscription: 0,
      hashVersion: "V2",
      returnData: "",
    });

    if (init.environment !== "TEST") console.warn("Init():", init.environment);

    const methods = document.getElementById("tlpy_payment_method");
    init.methods.forEach((m) => methods.add(new Option(m.name, m.id)));

    const cards = document.getElementById("tlpy_saved_cards");
    init.cards.forEach((c) => cards.add(new Option(c.name, c.id)));
  }

  document.getElementById("tlpy_cc_number").addEventListener("change", async () => {
    const brand = await Tilopay.getCardType();
    console.log(brand.message); // "visa", "mastercard", "amex"
  });

  document.getElementById("actualizar").addEventListener("click", async () => {
    await Tilopay.updateOptions({ billToTelephone: "87777777" });
  });

  document.getElementById("pagar").addEventListener("click", async () => {
    const payment = await Tilopay.startPayment();
    if (payment && payment.message) console.error(payment.message);
  });

  iniciar();
</script>

Cumplimiento#

Los datos de tarjeta no pasan por tu servidor, pero tu página los captura: consultá con tu equipo de cumplimiento el alcance que te corresponde.

Última verificación: 2026-10-22

Ver como Markdown crudo