SDK · Tilopay.Init()

SDK v2

Starts a purchase. It authenticates the checkout with the SDK token and returns the payment methods available to the merchant.

To save a card without charging it, the SDK has a second start flow: Tilopay.InitTokenize(), with the same parameters as Init() except amount, orderNumber, capture and subscription, which do not apply because nothing is charged.

Signature#

await Tilopay.Init({ /* parameters */ })

Parameters#

tokenstringrequerido#

SDK token, obtained with POST /api/v1/loginSdk. See authentication.

currencystringrequerido#

Purchase currency, ISO 4217.

languagestringrequerido#

Checkout language, ISO 639-1. Only es and en are supported; defaults to es.

amountdecimalrequerido#

Purchase amount.

billToEmailstringrequerido#

Customer email. Required for the response to include saved cards.

orderNumberstringrequerido#

Order number, unique per merchant. See safe retries.

typeDniinteger#

Customer identification type. Conditional. See the type table.

dnistring#

Customer identification number. Conditional.

billToFirstNamestringrequerido#

Customer first name.

billToLastNamestringrequerido#

Customer last name.

billToAddressstringrequerido#

Customer address line 1.

billToAddress2string#

Customer address line 2. Optional.

billToCitystring#

City. Recommended.

billToStatestring#

State or province. Recommended.

billToZipPostCodestring#

Postal code. Recommended.

billToCountrystring#

Country, ISO 3166-1 alpha-2. Recommended.

billToTelephonestring#

Customer phone. Recommended.

captureintegerrequerido#

0 authorizes; 1 authorizes and captures.

redirectstring (URL)requerido#

URL where the SDK renders the final purchase response.

subscriptionintegerrequerido#

1 saves the customer card in Tilopay; 0 does not save it.

phoneYappystring#

Yappy phone. Required when paying with Yappy. It is not read from the DOM.

hashVersionstring#

Optional. Values "V1" or "V2". If omitted, the final response hash is built with V1.

returnDatastring#

Optional. Returned as-is in the final payment response and recovered on the transaction response URL. Supports up to 65,535 characters, although a very long value can affect the response URL. You can send a base64-serialized array so it satisfies the string format.

Call#

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,
});

Response#

messagestring#

Success, or the error description.

testinteger#

0 production, 1 testing. See environments.

sinpemovilobject#

Object with code and amount, present when the merchant has SINPE Móvil. The full data, including the destination phone, is obtained with getSinpeMovil().

methodsarray#

Array of {id, name, type} with the available payment methods.

cardsarray#

Array of {id, name, brand} with the customer's saved cards.

Payment method id format#

Each method id has the shape A:B:C. The second segment defines the payment method, and 18 corresponds to Yappy.

Saved cards#

For the response to include cards, billToEmail is required.
Once the cards are obtained, the email can no longer be changed with updateOptions().

Last verified: 2026-08-28 · Owner: equipo-integraciones

View as raw Markdown