Tilopay.Init()
SDK 2.1.1Starts a purchase. It authenticates the checkout with the SDK token and returns the payment methods available to you.
To save a card without charging it, use
Tilopay.InitTokenize().
Signature#
await Tilopay.Init({ /* parameters */ })Parameters#
URL where Tilopay notifies the outcome of SINPE Móvil and Yappy payments.
Purchase currency, ISO 4217.
Checkout language: es or en.
Purchase amount.
Customer email. Needed for the response to include saved cards.
Order number. It cannot be repeated. See safe retries.
Customer identification type. Required for SINPE Móvil. See the type table.
Customer identification number. Required for SINPE Móvil.
Customer first name.
Customer last name.
Customer address line 1.
Customer address line 2.
City.
State or province.
Postal code.
Country, ISO 3166-1 alpha-2.
Customer phone.
Shipping recipient first name.
Shipping recipient last name.
Shipping address line 1.
Shipping address line 2.
Shipping city.
Shipping state or province.
Shipping postal code.
Shipping country, ISO 3166-1 alpha-2.
Shipping phone.
0 authorizes; 1 authorizes and captures.
URL where the SDK renders the final purchase response.
1 saves the customer card in Tilopay; 0 does not save it.
Values "V1" or "V2". If omitted, the final response hash is built with V2. It is
sent in this first call.
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.
Yappy phone. Required when paying with Yappy. It is not read from the DOM.
Call#
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,
});Response#
{
"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
}Success, or the error description.
"PROD" production, "TEST" testing. See environments.
Object with code and amount, present when you have SINPE Móvil. The full data,
including the destination phone, is obtained with
getSinpeMovil().
Array of {id, name, type, apple_pay} with available methods. type is card, sinpemovil or yappy; every method includes apple_pay (0 or 1).
Array of {id, name, brand} with the customer's saved cards.
On error#
On error:
{
"message": "<error description>",
"methods": [],
"cards": []
}Payment method id format#
Do not interpret the id: store it as-is as the select value and use each method's type field
(card, sinpemovil or yappy) to decide which fields to show.
Yappy#
The method has type: "yappy"; its id has the form <configId>:18:<merchantId>:….
The form needs the required Init() fields plus phoneYappy. Calling startPayment() redirects to a Tilopay page that opens Yappy; the customer approves in their app. When finished, Tilopay notifies webhook (if provided) and redirects to your redirect with code, auth, order and OrderHash. Cancellation rejects the order; without a response within 7 minutes, it becomes “Transaction expired”.
Saved cards#
- For the response to include
cards,billToEmailis required. - Once the cards are obtained, the email can no longer be changed with
updateOptions(). - The customer can pick a saved card or type a new one.
- When a saved card is picked, enable
tlpy_cvvso the customer can type the code.
Last verified: 2026-10-22