Stored cards and bulk collections

Destructive

What it covers#

This group works with the cards the merchant's 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 the merchant sees 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 the merchant's email.

The API routes used by bulk collections live outside the portal reference, so these pages do not publish them. What is documented is what each tool does, what it takes and what it returns.

Tools#

List collection groups

Read only

tilopay_saved_cards_list_groups

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

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.

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.

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).

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 with tilopay_saved_cards_create_payments (that one does 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

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 saved (tokenized) in Tilopay, identified by their email. Returns each card's token, which is what tilopay_charge_saved_card needs to charge them. Only cards saved with this assistant's link or the MCP's 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`.

API operation: POST /api/v1/processRecurrentPayment

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	—	Capture immediately (true by default)
`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.

API operation: POST /api/v1/user/card-remove

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. Sensitive operation: it moves real money.

Parameters

Parameter	Type	Required	Description
`reason`	string	yes	Reason for the charge, e.g. "Monthly fee"
`capture`	boolean	—	Capture immediately (true by default)
`users`	array<object>	—	Individual affiliates to charge. Each item: id (string, required), amount (number, required, greater than zero), currency (string, required), date (string "YYYY-MM-DD", empty = immediate)
`groups`	array<object>	—	Groups to charge. Each item: id (string, required), amount per affiliate (number, required, greater than zero), currency (string, required), date (string "YYYY-MM-DD", empty = immediate)
`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-09-14 · Owner: equipo-integraciones

View as raw Markdown