# SDK · Tilopay.Init()

> Inicia una compra: autentica el checkout y devuelve los métodos de pago disponibles y las tarjetas guardadas del cliente.

- kind: sdk-method
- status: stable
- sdk_version: v2
- last_verified: 2026-08-28
- url: https://www.tilopay.com/developers/sdk/reference/init

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 [#firma]

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

## Parámetros [#parametros]

<Param id="init-token" name="token" type="string" required>
Token del SDK, obtenido con `POST /api/v1/loginSdk`. Ver
[autenticación](/developers/api/autenticacion).
</Param>

<Param id="init-currency" name="currency" type="string" required>
Moneda de la compra, ISO 4217.
</Param>

<Param id="init-language" name="language" type="string" required>
**Idioma** del checkout, ISO 639-1. Solo se soportan `es` y `en`; por defecto carga `es`.
</Param>

<Param id="init-amount" name="amount" type="decimal" required>
Monto de la compra.
</Param>

<Param id="init-billtoemail" name="billToEmail" type="string" required>
Correo del cliente. Es obligatorio para que la respuesta traiga las tarjetas guardadas.
</Param>

<Param id="init-ordernumber" name="orderNumber" type="string" required>
Número de orden, único por comercio. Ver
[reintentos seguros](/developers/concepts/reintentos-seguros).
</Param>

<Param id="init-typedni" name="typeDni" type="integer">
Tipo de identificación del cliente. Condicionado. Ver la
[tabla de tipos](/developers/sdk/reference/update-options#tipos-de-identificacion).
</Param>

<Param id="init-dni" name="dni" type="string">
Número de identificación del cliente. Condicionado.
</Param>

<Param id="init-billtofirstname" name="billToFirstName" type="string" required>
Nombre del cliente.
</Param>

<Param id="init-billtolastname" name="billToLastName" type="string" required>
Apellidos del cliente.
</Param>

<Param id="init-billtoaddress" name="billToAddress" type="string" required>
Dirección 1 del cliente.
</Param>

<Param id="init-billtoaddress2" name="billToAddress2" type="string">
Dirección 2 del cliente. Opcional.
</Param>

<Param id="init-billtocity" name="billToCity" type="string">
Ciudad. Recomendado.
</Param>

<Param id="init-billtostate" name="billToState" type="string">
Provincia o estado. Recomendado.
</Param>

<Param id="init-billtozippostcode" name="billToZipPostCode" type="string">
Código postal. Recomendado.
</Param>

<Param id="init-billtocountry" name="billToCountry" type="string">
País, ISO 3166-1 alpha-2. Recomendado.
</Param>

<Param id="init-billtotelephone" name="billToTelephone" type="string">
Teléfono del cliente. Recomendado.
</Param>

<Param id="init-capture" name="capture" type="integer" required>
`0` autoriza; `1` autoriza y captura.
</Param>

<Param id="init-redirect" name="redirect" type="string (URL)" required>
URL donde el SDK renderiza la respuesta final de la compra.
</Param>

<Param id="init-subscription" name="subscription" type="integer" required>
`1` guarda la tarjeta del cliente en Tilopay; `0` no la guarda.
</Param>

<Param id="init-phoneyappy" name="phoneYappy" type="string">
Teléfono Yappy. Obligatorio cuando se paga con Yappy. No se toma del DOM.
</Param>

<Param id="init-hashversion" name="hashVersion" type="string">
Opcional. Valores `"V1"` o `"V2"`. Si no se envía, el hash de la respuesta final se fabrica
con V1.
</Param>

<Param id="init-returndata" name="returnData" type="string">
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.
</Param>

## Llamada [#llamada]

```js
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 [#respuesta]

<Param id="init-res-message" name="message" type="string">
`Success`, o la descripción del error.
</Param>

<Param id="init-res-test" name="test" type="integer">
`0` producción, `1` pruebas. Ver [entornos](/developers/concepts/entornos).
</Param>

<Param id="init-res-sinpemovil" name="sinpemovil" type="object">
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()`](/developers/sdk/reference/get-sinpe-movil).
</Param>

<Param id="init-res-methods" name="methods" type="array">
Arreglo de `{id, name, type}` con los métodos de pago disponibles.
</Param>

<Param id="init-res-cards" name="cards" type="array">
Arreglo de `{id, name, brand}` con las tarjetas guardadas del cliente.
</Param>

## Formato del id de método de pago [#formato-id-metodo]

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 [#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()`](/developers/sdk/reference/update-options).