Stored cards and bulk collections

Includes sensitive operations

What it covers#

This group works with the cards your customers already authorised to store (tokenization) and with bulk collections against those cards.

How storing works: the agent generates a secure link and shares it with the customer; the customer types their card there. Neither the agent, nor the model, nor you see the full number: the read tools return the brand and the last digits.

The sensitive operations in this group — charging a stored card, removing a card and creating bulk collections — require a confirmation code sent to your email.

Saved card payments API reference.

Tools#

List collection groups

Read only

tilopay_saved_cards_list_groups

Lists the collection groups with stored cards (affiliates) in Tilopay.

API operation: POST /api/v1/collect/get/groups — see the operation page

Parameters

No parameters.

Returns

{ result }

Raw Tilopay API response under the `result` key.

List affiliates with a stored card

Read only

tilopay_saved_cards_list_affiliates

Lists the affiliates (customers with a stored card) of a collection group.

API operation: POST /api/v1/collect/get/affiliates — see the operation page

Parameters

Parameter	Type	Required	Description
`group`	integer	—	Group ID (0 for all)

Returns

{ result }

Raw Tilopay API response under the `result` key.

List bulk collections

Read only

tilopay_saved_cards_list_collections

Lists the bulk collections made with stored cards in Tilopay.

API operation: POST /api/v1/collect/get/massive — see the operation page

Parameters

No parameters.

Returns

{ result }

Raw Tilopay API response under the `result` key.

Bulk collection detail

Read only

tilopay_saved_cards_collection_detail

Returns the detail of a bulk collection. It requires the collection `code` (the `code` field returned by tilopay_saved_cards_list_collections).

API operation: POST /api/v1/collect/get/massive/detail — see the operation page

Parameters

Parameter	Type	Required	Description
`code`	string	yes	Bulk collection code (the `code` field of the collections list)

Returns

{ result }

Raw Tilopay API response under the `result` key.

Save a customer's card (tokenize)

Write

tilopay_tokenize_card

Generates the secure Tilopay link where the customer enters their card to have it saved (tokenized). The merchant never sees or receives the card data. Once saved, it can be charged in bulk with tilopay_saved_cards_create_payments or individually with tilopay_charge_saved_card (both ask for a confirmation code by email). If a contact or phone is given, it also returns a WhatsApp link with the message ready to send to the customer.

API operation: POST /api/v1/processTokenize — see the operation page

Parameters

Parameter	Type	Required	Description
`email`	string	yes	Cardholder's email
`first_name`	string	yes	Cardholder's first name
`last_name`	string	yes	Cardholder's last name
`language`	string (es \| en)	—	Form language (es by default)
`redirect_url`	string	—	URL the customer returns to when finished (optional)
`contact_name`	string	—	Name of the saved contact or of the customer, to draft the WhatsApp message
`phone`	string	—	Customer's WhatsApp phone, e.g. +50688887777
`message`	string	—	Your own text for the message to the customer
`save_contact`	boolean	—	Save the contact in the address book

Returns

{ tokenize_url, whatsapp_url, email, contact }

tokenize_url = secure link where the customer enters their card to save it; whatsapp_url = WhatsApp link ready to send it. The card is typed by the customer: the agent never receives the number.

List a customer's saved cards

Read only

tilopay_list_customer_cards

Lists the cards a customer already has stored (tokenized) in Tilopay, identified by the customer's email. Returns the token of each card, which is what tilopay_charge_saved_card needs to charge it. Only cards stored with the link of this assistant or of the MCP can be charged. It does not charge anything.

Parameters

Parameter	Type	Required	Description
`email`	string	yes	Email of the customer who owns the cards
`currency`	string	—	Reference currency, e.g. CRC or USD. If omitted, the merchant's country currency is used.

Returns

{ cards, count }

cards = that customer's already saved cards, with brand, last digits and their identifier to charge; count = how many there are. It never returns the full card number.

Available payment methods and installments

Read only

tilopay_payment_methods

Lists the payment methods enabled for the merchant in the Tilopay checkout (cards, SINPE Móvil, Yappy, installments or zero rate when active) and whether the account responds in production or test. Use it when the merchant asks what they can offer their customer or whether they have installments / zero rate.

Parameters

Parameter	Type	Required	Description
`amount`	number	—	Reference amount; some methods and installments depend on the amount
`currency`	string	—	Reference currency. If omitted, the merchant's country currency is used.
`email`	string	—	Customer email (optional; only to also see their saved cards)

Returns

{ methods, installments, cards, environment, currency }

methods = payment methods enabled for the merchant; installments = installments available when the method allows them; cards = customer's saved cards if their email was sent; environment = production or test.

Charge a customer's saved card

Sensitive

tilopay_charge_saved_card

Charges an amount to a customer's already saved (tokenized) card. Requires the customer's email and the card token (obtained with tilopay_list_customer_cards). Sensitive operation: it moves real money and requires a second factor. Call it first without `confirmation_code`: a 6-digit code is sent to the merchant's email and the response carries `requires_confirmation`. Repeat the same call, with the same parameters, adding `confirmation_code`.

Requires confirmation: Confirmations Tilopay requires

API operation: POST /api/v1/processRecurrentPayment — see the operation page

Parameters

Parameter	Type	Required	Description
`email`	string	yes	Cardholder's email
`card`	string	yes	Token of the saved card (v2 version)
`amount`	number	yes	Amount to charge
`currency`	string	—	Currency of the charge. If omitted, the merchant's country currency is used.
`order_number`	string	—	Order number; if omitted a unique one is generated
`capture`	boolean	—	Shown in the authorization email but currently not sent in the charge.
`confirmation_code`	string	—	6-digit code received by email to authorize the operation

Returns

{ result, approved, orderNumber, currency, receipt_code, receipt_url, receipt_image_url }

Charges an already saved card of the customer: approved = whether the charge was approved; orderNumber = generated order number; receipt_* = the charge's receipt when generated. Requires a second factor by email.

Delete a customer's saved card

Sensitive

tilopay_remove_saved_card

Deletes a customer's saved card (token) in Tilopay. Sensitive operation: requires a second factor. Call it first without `confirmation_code` and repeat it later with the 6-digit code sent to the merchant's email.

Requires confirmation: Confirmations Tilopay requires

API operation: POST /api/v1/user/card-remove — see the operation page

Parameters

Parameter	Type	Required	Description
`email`	string	yes	Email of the customer who owns the card
`token`	string	yes	Token of the card to delete
`confirmation_code`	string	—	6-digit code received by email to authorize the operation

Returns

{ result }

result = API response deleting the customer's saved card. Requires a second factor by email.

Charge stored cards

Sensitive

tilopay_saved_cards_create_payments

Creates charges to affiliates and/or groups with stored cards in Tilopay (owner only; requires the confirmation code sent by email). Only affiliates whose cards were saved with tilopay_tokenize_card can be charged; in a group, all its members must qualify. No idempotency: repeating the operation with a new code charges again. currency and capture appear in the authorization email but are currently not sent in the charge.

Requires confirmation: Confirmations Tilopay requires

API operation: POST /api/v1/collect/set/payments — see the operation page

Parameters

Parameter	Type	Required	Description
`reason`	string	yes	Reason for the charge, e.g. "Monthly fee"
`capture`	boolean	—	Shown in the authorization email but currently not sent in the charge.
`users`	array<object>	—	Array of { id: string, amount: number > 0, currency: string, date?: "YYYY-MM-DD" }; date schedules the charge; currency is shown in the authorization email but is not sent in the charge
`groups`	array<object>	—	Array of { id: string, amount: number > 0 (amount per affiliate), currency: string, date?: "YYYY-MM-DD" }; currency is shown in the authorization email but is not sent in the charge
`confirmation_code`	string	—	6-digit code received by email to authorize the operation

Returns

{ result }

Raw Tilopay API response under the `result` key.

Last verified: 2026-10-20

View as raw Markdown