The commerce domain uses four primary tables: orders, usersplans, payments, and shippingnotes. Each represents a distinct layer of the transaction lifecycle.

When a tenant saves payment settings in the control panel, the platform makes a live API call to the gateway to verify the credentials work. This is not format validation; it is a real request to the gateway using the credentials the tenant just entered. If the call fails, the save is rejected.

The gateway_type column on Orders identifies the payment gateway or assignment source. Not all values represent real payment processors; several represent administrative or institutional assignment paths that never touch a payment gateway.

The checkout does not let the user choose which gateway to use. The platform selects it automatically from the tenant's configured gateways, picking the first one (in priority order) whose supported currencies include the cart's currency.

Terms used across the commerce domain that are either non-obvious, have names that conflict with their meaning, or are used inconsistently across the codebase.

Adding a currency touches two surfaces; both must be updated, or the currency appears in plan-creation UIs but no gateway is ever offered for it at checkout. Use this guide when onboarding a new currency end-to-end.

Each payment gateway sends webhook notifications to Farfalla when payment state changes. All gateways share a single IPN controller, exposed at two routes:

These order types have one thing in common: none of them go through a payment gateway at checkout time. No gateway call is made, and access is granted immediately.

The payments table works like a bank ledger: every financial event is a new row. Financial fields are never mutated after insert. This is not an accident; it is the core invariant that makes balance calculation correct.

A set of scheduled jobs keep gateway transaction state aligned with Farfalla's orders and payments tables. They cover gateway-initiated changes that did not reach the platform through an Instant Payment Notification (see IPNs): status updates, gateway keys, and missing payment rows.

Entry point into the payments domain: the four active gateways (MercadoPago, Stripe, Yuno, PayU), coupons, manual payments, and the standard checkout flow.

A refund can arrive through three conceptual paths. Each path ends by inserting a new row in payments with status = 'refunded'; the original approved row is never modified. See Payment Ledger Model.

When a user buys a physical product, the checkout records two separate entries in the payments table: one for the product, one for the carrier cost. The carrier cost entry has no associated UserPlan.

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

Yuno has two checkout flows that behave differently with respect to order creation:

Summary

Yuno is a payment orchestrator that allows Farfalla to offer multiple payment methods (cards, local wallets, bank transfers, etc.) through a single integration. In Farfalla it is integrated as one more gateway, behind the feature flag yunocheckoutenabled.

Summary

Summary

Summary

Summary