Recurring billing

tilopay_recurring_list_plans

Lists the recurring billing plans configured in Tilopay.

API operation: POST /api/v1/getPlansRepeat

Parameters

No parameters.

Returns

{ result }

Raw Tilopay API response under the `result` key.

tilopay_recurring_get_plan

Returns the detail of a recurring billing plan by its ID.

API operation: POST /api/v1/getPlanRepeat

Parameters

Returns

{ result }

Raw Tilopay API response under the `result` key.

tilopay_recurring_get_subscriber

Returns the detail of a subscriber of a recurring plan by its ID.

API operation: POST /api/v1/getSuscriptorRepeat

Parameters

Returns

{ result }

Raw Tilopay API response under the `result` key.

tilopay_recurring_subscriber_payments

Lists the payments made by a recurring subscriber.

API operation: POST /api/v1/getSuscriptorPayments

Parameters

Returns

{ result }

Raw Tilopay API response under the `result` key.

tilopay_recurring_failed_payments

Lists the latest recurring charges that failed (plan, subscriber, amount, date and reason). One call is enough.

API operation: POST /api/v1/getSuscriptorPayments

Parameters

Returns

{ total, source, failures[] }

failures = declined recurring charges, with plan, subscriber, amount, currency and decline reason; total = how many were found; source = the API route they were obtained from. It combines the query of plans, subscribers and their payments.

tilopay_recurring_manage_subscriber

Pauses, reactivates or deletes a subscriber of a recurring plan in Tilopay. Sensitive operation: it affects future charges.

API operation: POST /api/v1/pauseSuscriptorRepeat, /reactiveSuscriptorRepeat o /deleteSuscriptorRepeat

Parameters

Returns

{ result }

Raw response of the endpoint matching the action: pause, reactivate or delete.

tilopay_recurring_create_plan

Creates a recurring billing plan (subscription) in Tilopay with its title, currency, frequency and modalities (name and amount). Returns the ID of the created plan; then use tilopay_recurring_subscription_url to get the link customers use to subscribe.

API operation: POST /api/v1/createPlanRepeat

Parameters

Returns

{ result, currency, frequency }

result = API response with the created plan; currency and frequency = the currency and frequency the plan ended up with.

tilopay_recurring_edit_plan

Modifies an existing recurring billing plan: title, description, frequency, currency, amount per cycle (modality), initial payment, free trial, retries, status or end date. First check tilopay_recurring_get_plan to know the current values.

API operation: POST /api/v1/editPlanRepeat

Parameters

Returns

{ result }

result = API response editing the plan. Fields that are not sent are kept.

tilopay_recurring_delete_plan

Deletes a recurring billing plan in Tilopay. It affects the plan's future charges: confirm with the merchant before running it.

API operation: POST /api/v1/deletePlanRepeat

Parameters

Returns

{ result }

result = API response deleting the plan. The plan's subscribers stop being charged.

tilopay_recurring_subscription_url

Returns the link a customer uses to sign up for a recurring plan (or renew it if the email is already subscribed). Deliver the full URL, without shortening it.

API operation: POST /api/v1/recurrentUrl

Parameters

Returns

{ url, result }

url = subscription link for the plan, to share with the customer; result = the raw API response.

tilopay_recurring_edit_subscriber

Changes a subscriber's status (active, paused or deleted) and/or its expiration date. It affects future charges: confirm with the merchant before running it.

API operation: POST /api/v1/editSuscriptorRepeat

Parameters

Returns

{ result }

result = API response editing the subscriber's data (email, phone, amount or expiration date, depending on the plan).

tilopay_recurring_create_coupon

Creates a discount coupon for a subscription plan: percentage or fixed amount, expiration date, allowed emails and usage limits.

API operation: POST /api/v1/createCoupon

Parameters

Returns

{ result }

result = API response with the discount coupon created for the plan.

tilopay_recurring_list_coupons

Lists the discount coupons associated with a subscription plan.

API operation: POST /api/v1/getRepeatCoupons

Parameters

Returns

{ result }

result = the plan's coupons as returned by the API.

tilopay_recurring_get_coupon

Returns the detail of a discount coupon by its ID.

API operation: POST /api/v1/getCoupon

Parameters

Returns

{ result }

result = coupon detail as returned by the API.

tilopay_recurring_delete_coupon

Deletes a discount coupon of a subscription plan.

API operation: POST /api/v1/deleteCoupon

Parameters

Returns

{ result }

result = API response deleting the coupon.

tilopay_recurring_plan_wizard_start

Starts the guided step-by-step to create (mode=create) or edit (mode=edit with plan_id) a subscription plan. Returns the first pending question: deliver it to the merchant as is and pass their answer to tilopay_recurring_plan_wizard_answer. Use it instead of tilopay_recurring_create_plan when some data is missing.

Parameters

Returns

{ draft }

draft = the plan draft in progress, with what has already been answered and the next pending step. It creates nothing in Tilopay until confirmed.

tilopay_recurring_plan_wizard_answer

Saves the merchant's answer to the current step of the subscription plan and returns the next question or the summary to confirm. Deliver the returned text as is, without adding questions of your own.

Parameters

Returns

{ draft }

draft = the updated draft with the step's answer and the next pending step.

tilopay_recurring_plan_wizard_confirm

Creates or edits the subscription plan with the step-by-step data, after the merchant said yes to the summary. When creating, it also returns the subscription link: deliver it in full, without shortening it.

API operation: POST /api/v1/createPlanRepeat

Parameters

No parameters.

Returns

{ plan_id, subscription_url }

Creates the plan with what was built step by step: plan_id = id of the created plan; subscription_url = subscription link to share.

tilopay_recurring_plan_wizard_cancel

Discards the subscription plan that was in progress without creating or changing anything.

Parameters

No parameters.

Returns

Discards the plan draft in progress. It creates or changes nothing in Tilopay; it only returns the confirmation in text.

tilopay_recurring_settle_link

Creates a payment link for the amount of a recurring charge that failed and associates it with the plan's subscriber. When the customer pays that link, the subscription is settled automatically: the subscriber is reactivated and its expiration date moves to the next cycle. Use it when the merchant agrees to send the link to the customer of a failed charge (the data comes from tilopay_recurring_failed_payments). Returns the link URL and, if there is a phone number, a WhatsApp link ready to send to the customer.

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

Parameters

Returns

{ url, linkId, whatsapp_url, currency, amount, subscriber_id, frequency }

Creates a one-time payment link for the subscriber to settle a failed recurring charge: url = payment link; whatsapp_url = WhatsApp link ready to send it; linkId = id of the created link.

tilopay_recurring_mark_settled

Marks the subscriber as settled on their plan: leaves them active and moves their expiration date to the next cycle. Use it when the pending charge has already been paid through another channel. If the payment was made with the tilopay_recurring_settle_link link, this is not needed: it updates itself. Confirm with the merchant before running it.

API operation: POST /api/v1/editSuscriptorRepeat

Parameters

Returns

{ ok, expire, frequency }

Moves the subscriber's due date forward according to the plan's frequency, to settle them after recovering a failed charge. expire = the new expiration date.