Subscriptions Flow with MercadoPago

This document covers the MercadoPago-specific subscription checkout flow. For the IPN lifecycle and refund handling, see IPNs and Refund Flow.

Starting from when a customer presses the Subscription button and selects MercadoPago:

Process		Location
Create a unique Order with information about the plan to be acquired.		publica.la
Create the Checkout based on the Order/Plan data. This will generate a unique identifier (external_reference) using data from the Order/Plan and the discount coupon if applicable		publica.la
This unique identifier refers to the Plan within the Tenant. If it's the first time a customer subscribes, it will be created in MercadoPago; otherwise, it will only provide the URL for subscribing. The credentials used will be the ones linked to the Order, which can be either Publicala's credentials or the Tenant's own credentials for their MercadoPago account.		publica.la
If it's the first time	If it already exists	MercadoPago
Check if there is a PreapprovalPlan that matches the unique identifier (external_reference). If not found, proceed with the following creation process: reason: indicates the title of the Plan. external_reference: indicates the unique identifier for the subscription. back_url: indicates that it should return to the route: receivePayment specifying the gateway and external_reference. auto_recurring: indicates the frequency of the plan (monthly or yearly), the amount, and the currency.	Check if there is a PreapprovalPlan that matches the unique identifier (external_reference). If found, return the data of that plan to direct the user to subscribe to it.	MercadoPago
Having the PreapprovalPlan created, redirect the user to the URL provided by MercadoPago to subscribe to the plan (PreapprovalPlan->init_point), and the Order status becomes Pending.		publica.la
Logged into MercadoPago	Not logged into MercadoPago	MercadoPago
Create a preference with the user's data (email in MercadoPago) and provide all the information about their account: Available Cards Available Balance Payment Methods and applicable discounts etc.	Allow loading card information, which will be validated by MercadoPago at that moment. If no valid card information is provided, the user will be prompted to enter a valid email. If that fails, the user will be directed to their MercadoPago account as if they were logged in. At this point, MercadoPago will verify the process and decide whether it might be a fraud, suspicious, or if the operation needs validation later on. The preference is created at the end of the flow with the provided data.	MercadoPago
Here, the purchase/payment confirmation occurs within MercadoPago. If the operation is successful, MercadoPago will inform us and provide a button to return to the original site. With the IPN system, an announcement of the successful subscription is triggered. The URL that receives the notification depends on the credentials being used, but the configuration must point to the route: http://tenant_url/payment/ipn/mercadopago.		MercadoPago
A first IPN notification arrives. The platform looks up the order using the IPN's payload (see "IPNs" below): first by gateway_key, then by the order UUID carried in the preapproval's external_reference. The payer email is recorded for debugging only and is not used to match the order.		publica.la
The user returns to the site	The user closes the window	MercadoPago
It returns to the back_url set in the plan, going to the route receivePayment, which retrieves the data of the successfully created subscription (the gateway_key associated with the user) and completes the order approval flow.	The IPN flow continues server-side regardless. The order is approved when the platform can resolve it through gateway_key or the external_reference UUID. Only if neither lookup finds the order does it stay pending and get surfaced in the Nova "Pending Subscriptions" resource for manual linkage.	publica.la
The Order is approved, and the thank you message is displayed.		publica.la

IPNs (Instant Payment Notification)

MercadoPago sends IPN webhooks to notify of subscription events: new subscriptions, renewals, cancellations, payment failures, and status changes.

When a subscription IPN arrives, the platform finds the associated Order in two steps:

1. By gateway_key: the subscription ID from MercadoPago. This is the primary path for recurring billing IPNs, since the gateway_key was set on the first successful cycle.
2. By external_reference: the Order UUID that was embedded in the PreapprovalPlan's back_url at creation time. This handles the first IPN, before the gateway_key is set on the Order.

If the Order is found by UUID but already has a different gateway_key, MercadoPago created a duplicate subscription. The duplicate is cancelled and the user is notified, but only if (a) the preapproval status is not already cancelled, and (b) the cache key mp_duplicate_subscription_{preapproval_id} is not already set. The cache key is held for 5 minutes to suppress repeated cancellation attempts caused by IPN bursts.

If the Order cannot be found by either method, the IPN is logged and requires manual intervention via the Nova resource at {tenant_url}/nova/resources/pending-subscriptions.

Legacy external reference format

If the preapproval's external_reference contains the substring _plan_, the IPN is treated as the legacy format that predates the UUID convention. The handler tags it requires_manual_action and skips processing. These cases require operator linkage; no automatic recovery exists for them.