This information may be outdated. :::

Confirm with the rest of the team before considering this information as valid. :::

Subscriptions Flow with MercadoPago

We will start with a customer who is about to press the Subscription button and decides to pay with MercadoPago. Here is the following flow:

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: receiveNewSubscription specifying he 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
We receive a first IPN notification, which we can't identify unless the payer's email matches the one used to create the order. This first notification is mostly irrelevant.		publica.la
The user returns to the site	The user closes the window	MercadoPago
It returns to the back_url set in the plan, indicating that it should go to the route receiveNewSubscription to retrieve the data of the successfully created subscription (gateway_key associated with the user). Once the information is completed, it follows the normal flow to receivePayment.	The order remains pending and can only be approved if the same email exists both in the Tenant and in MercadoPago. Otherwise, it must be assigned with a Nova resource created for such situations (Pending Subscriptions).	publica.la
The Order is approved, and the thank you message is displayed.		publica.la

IPNs (Instant Payment Notification)

This is the current system used to receive notifications from MercadoPago. It informs us of any updates or changes that occur with a payment in MercadoPago, such as deactivating/pausing a subscription or notifying us if a card has been rejected due to insufficient funds or suspected fraud, among others.

Focusing on the Subscription flow and the new implementation we made, our operation is relatively straightforward. We use the payment information provided to obtain and complete any pending data for the Order. The gateway_key found in the orders serves to associate it if the user completed the process correctly. Otherwise, we try to make the association using the email (the same email in the tenant used for the payment). If this also fails, and it's the first time the payment process was created and its status is approved, we proceed to notify the information to a Slack channel (#mp-subscription-notifications) with the available data from the payment. Later, we manually associate it with the order using Nova (https://app.publica.la/nova/resources/pending-subscriptions).

---