Tilopay.Init()

SDK 2.1.1

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

Para guardar una tarjeta sin cobrarla, usá Tilopay.InitTokenize().

Firma#

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

Parámetros#

webhookstring#

URL a la que Tilopay notifica el resultado de pagos con SINPE Móvil y Yappy.

tokenstringrequerido#

Token del SDK, obtenido por tu backend con POST /api/v1/loginSdk. Ver token del SDK.

currencystringrequerido#

Moneda de la compra, ISO 4217.

languagestringrequerido#

Idioma del checkout: es o en.

amountdecimal (12,2)requerido#

Monto de la compra.

billToEmailstringrequerido#

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

orderNumberstringrequerido#

Número de orden. No se puede repetir. Ver reintentos seguros.

typeDniinteger#

Tipo de identificación del cliente. Obligatorio para SINPE Móvil. Ver la tabla de tipos.

dnistring#

Número de identificación del cliente. Obligatorio para SINPE Móvil.

billToFirstNamestring#

Nombre del cliente.

billToLastNamestring#

Apellidos del cliente.

billToAddressstring#

Dirección 1 del cliente.

billToAddress2string#

Dirección 2 del cliente.

billToCitystring#

Ciudad.

billToStatestring#

Provincia o estado.

billToZipPostCodestring#

Código postal.

billToCountrystring#

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

billToTelephonestring#

Teléfono del cliente.

shipToFirstNamestring#

Nombre de quien recibe el envío.

shipToLastNamestring#

Apellidos de quien recibe el envío.

shipToAddressstring#

Dirección 1 de envío.

shipToAddress2string#

Dirección 2 de envío.

shipToCitystring#

Ciudad de envío.

shipToStatestring#

Provincia o estado de envío.

shipToZipPostCodestring#

Código postal de envío.

shipToCountrystring#

País de envío, ISO 3166-1 alpha-2.

shipToTelephonestring#

Teléfono de envío.

captureinteger#

0 autoriza; 1 autoriza y captura.

redirectstring (URL)#

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

subscriptioninteger#

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

hashVersionstring#

Valores "V1" o "V2". Si no se envía, el hash de la respuesta final se fabrica con V2. Se envía en esta primera llamada.

returnDatastring#

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.

phoneYappystring#

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

Llamada#

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

Respuesta#

{
  "message": "Success",
  "environment": "PROD",
  "sinpemovil": { "code": "TB095", "amount": "100.00" },
  "methods": [
    { "id": "<id_del_metodo_tarjeta>", "name": "Tarjeta", "type": "card", "apple_pay": 0 },
    { "id": "<id_del_metodo_sinpe>", "name": "SINPE Móvil", "type": "sinpemovil", "apple_pay": 0 }
  ],
  "cards": [
    { "id": "411112555451111:Ref", "name": "4111********1111", "brand": "visa" }
  ],
  "applePaySupported": false
}

messagestring#

Success, o la descripción del error.

environmentstring#

"PROD" producción, "TEST" pruebas. Ver entornos.

sinpemovilobject#

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

methodsarray#

Arreglo de {id, name, type, apple_pay} con los métodos de pago disponibles. type vale card, sinpemovil o yappy; cada método trae apple_pay (0 o 1).

cardsarray#

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

applePaySupportedboolean#

true cuando se cumplen los requisitos de Apple Pay para ese dominio y navegador.

En caso de error#

En caso de error:

{
  "message": "<descripción del error>",
  "methods": [],
  "cards": []
}

Formato del id de método de pago#

No interpretes el id: guardalo tal cual como valor del select y usá el campo type de cada método (card, sinpemovil o yappy) para decidir qué campos mostrar.

Yappy#

El método trae type: "yappy"; su id tiene la forma <configId>:18:<merchantId>:….

El formulario necesita los campos obligatorios de Init() más phoneYappy. Al llamar startPayment(), el SDK redirige a una página de Tilopay que abre Yappy; el cliente aprueba el pago en su app. Al terminar, Tilopay notifica al webhook (si se envió) y redirige a tu redirect con code, auth, order y OrderHash. Si cancela, la orden queda rechazada; sin respuesta en 7 minutos, queda como “Transacción expirada”.

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().
El cliente puede elegir una tarjeta guardada o digitar una nueva.
Al elegir una tarjeta guardada, habilitá tlpy_cvv para que el cliente digite el código.

Última verificación: 2026-10-22

Ver como Markdown crudo