SDK · Tilopay.Init()

SDK v2

Inicia una compra. Autentica el checkout con el token del SDK y devuelve los métodos de pago disponibles para el comercio.

Para guardar una tarjeta sin cobrarla, el SDK tiene un segundo flujo de inicio: Tilopay.InitTokenize(), con los mismos parámetros de Init() excepto amount, orderNumber, capture y subscription, que no aplican porque no se está cobrando nada.

Firma#

await Tilopay.Init({ /* parámetros */ })

Parámetros#

tokenstringrequerido#

Token del SDK, obtenido con POST /api/v1/loginSdk. Ver autenticación.

currencystringrequerido#

Moneda de la compra, ISO 4217.

languagestringrequerido#

Idioma del checkout, ISO 639-1. Solo se soportan es y en; por defecto carga es.

amountdecimalrequerido#

Monto de la compra.

billToEmailstringrequerido#

Correo del cliente. Es obligatorio para que la respuesta traiga las tarjetas guardadas.

orderNumberstringrequerido#

Número de orden, único por comercio. Ver reintentos seguros.

typeDniinteger#

Tipo de identificación del cliente. Condicionado. Ver la tabla de tipos.

dnistring#

Número de identificación del cliente. Condicionado.

billToFirstNamestringrequerido#

Nombre del cliente.

billToLastNamestringrequerido#

Apellidos del cliente.

billToAddressstringrequerido#

Dirección 1 del cliente.

billToAddress2string#

Dirección 2 del cliente. Opcional.

billToCitystring#

Ciudad. Recomendado.

billToStatestring#

Provincia o estado. Recomendado.

billToZipPostCodestring#

Código postal. Recomendado.

billToCountrystring#

País, ISO 3166-1 alpha-2. Recomendado.

billToTelephonestring#

Teléfono del cliente. Recomendado.

captureintegerrequerido#

0 autoriza; 1 autoriza y captura.

redirectstring (URL)requerido#

URL donde el SDK renderiza la respuesta final de la compra.

subscriptionintegerrequerido#

1 guarda la tarjeta del cliente en Tilopay; 0 no la guarda.

phoneYappystring#

Teléfono Yappy. Obligatorio cuando se paga con Yappy. No se toma del DOM.

hashVersionstring#

Opcional. Valores "V1" o "V2". Si no se envía, el hash de la respuesta final se fabrica con V1.

returnDatastring#

Opcional. Se devuelve tal cual en la respuesta final del pago y se recupera en la URL de respuesta de la transacción. Soporta hasta 65.535 caracteres, aunque un valor muy extenso puede afectar la URL de respuesta. Podés enviar un array serializado en base64 para que cumpla el formato de string.

Llamada#

const init = await Tilopay.Init({
  token: sdkToken,
  currency: "CRC",
  language: "es",
  amount: 100.0,
  billToEmail: "cliente@ejemplo.com",
  orderNumber: "ORD-2026-000123",
  billToFirstName: "Ana",
  billToLastName: "Rojas",
  billToAddress: "Avenida 1, Local 2",
  billToCountry: "CR",
  capture: 1,
  redirect: "https://ejemplo.com/checkout/respuesta",
  subscription: 0,
});

Respuesta#

messagestring#

Success, o la descripción del error.

testinteger#

0 producción, 1 pruebas. Ver entornos.

sinpemovilobject#

Objeto con code y amount, presente cuando el comercio tiene SINPE Móvil. Los datos completos, incluido el teléfono destino, se obtienen con getSinpeMovil().

methodsarray#

Arreglo de {id, name, type} con los métodos de pago disponibles.

cardsarray#

Arreglo de {id, name, brand} con las tarjetas guardadas del cliente.

Formato del id de método de pago#

El id de cada método tiene la forma A:B:C. El segundo segmento define el método de pago, y 18 corresponde a Yappy.

Tarjetas guardadas#

Para que la respuesta traiga cards es obligatorio enviar billToEmail.
Una vez obtenidas las tarjetas, el correo ya no se puede cambiar con updateOptions().

Última verificación: 2026-08-28 · Responsable: equipo-integraciones

Ver como Markdown crudo