Skip to main content
  • Send to AI

Payments Overview

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

Coupons​

Coupons offer discounts and promotions to users on the platform. They can be configured from the control panel by an administrator.

Coupon Configuration Options​

  • The coupon discount is managed as a percentage, ranging from 1% to 100%.
  • You can set a usage limit, for example, 100 uses or 1 use for single-use coupons.
  • A validity or expiration date can be set for the coupon.
  • A coupon can be applied to both one-time product purchases and subscriptions.
  • You can limit a user to use a coupon only once.
  • The number of uses per publication can be limited.
  • You can set the coupon so that once it is redeemed, the discount is valid until the end of the month in which it was redeemed.

Manual Payments​

Manual payments allow for the registration of charges that occur outside the platform. These can be done from the dashboard, bulk import, orders API, or an integration that assigns content (LTI or SAML)

Gateways​

The platform supports the following active payment gateways. Payments through gateways can be made using either Publica.la credentials or the tenant's own credentials.

MercadoPagoStripeYunoPayU
One-off paymentYesYesYesYes (legacy)
Recurring paymentYesYesYes (*)No
Publica.la credentialsYesYesNoNo
IPN notificationsYesYesYesNo
Reader/Gift supportYesYesNoNo
Partial refundYesYesYesNo
CurrenciesARS, MXN, COP, PEN, CLP, UYUStripe docsARS, USD (with conversion)ARS, COP, MXN, USD, PEN, CLP

* Yuno recurring is not declared in config/payments.php under payment_type_gateway_mapping.recurring (only mercadopago and stripe are). Yuno handles subscription cycles via its own vault-on-success path and the CheckYunoRecurringPayments job, bypassing that standard mapping. Code that relies on the recurring gateway mapping will not include Yuno; code that reads per-gateway supported_currencies plus Yuno-specific paths will.

Gateway selection is driven by each gateway's supported_currencies and order columns on the gateways table. See Gateway Routing for the routing logic. plans_gateways_meta stores per-plan remote identifiers and prices and is not the routing source.

warning

PayU is a legacy gateway with several restrictions. See Gateway References — PayU.

Deprecated

PayPal was removed from the active gateway set. Existing PayPal recurring subscriptions are being cancelled by an ongoing background process (CancelPaypalRecurringSubscriptions). New orders cannot route to PayPal. See Deprecated gateways.

MercadoPago​

MercadoPago is the primary gateway for Latin American tenants, particularly Argentina. It supports one-time and recurring payments using either Publica.la credentials (Argentina) or tenant-owned credentials.

Resources​

Stripe​

Stripe is the primary gateway for international tenants and supports most currencies. Charges in Brazilian Reals require Publica.la's dedicated Brazil credentials and a mandatory CPF field in the checkout form.

Yuno​

Yuno is a payment orchestrator integrated as a standard gateway. It supports one-time and recurring payments. Recurring subscriptions use a vault-on-success approach: the initial charge is a one-off with vault_on_success: true. Yuno bills subsequent cycles autonomously per the subscription frequency, sending each successful charge back as an IPN. CheckYunoRecurringPayments (every 5 minutes) reconciles state only: it pauses or cancels orders when expected payments are missing, but does not issue charges.

Yuno's subscription flow differs from other gateways: the Farfalla order is created inside the recurring payment service, after the user completes the Yuno checkout step. The one-off (OTT) flow follows the standard sequence and creates the order before the payment call. See Yuno Checkout Flow for details.

  • Feature flag: yuno_checkout_enabled

PayU (legacy)​

PayU is a legacy gateway used by some existing tenants. See Gateway References — PayU for the full set of restrictions (no new tenants, one-off only, no refund path, not available in reader or gift flows).

IPNs​

The platform exposes two IPN entry points (implemented for MercadoPago, Stripe, and Yuno):

  • payment/ipn/{gateway_type} (web route, named receivePaymentEvents). Used by MercadoPago, Stripe, and Yuno.
  • ipn/{gateway_type} (API route under /api/v1, named receivePaymentEventsApi). Used by PayU.

Both routes resolve to the same IPN controller; see IPNs.

At the time of each operation, or any subsequent modification of it, the platform receives an update notification via IPN. With that notification, the platform retrieves the updated data from the gateway and synchronizes it with the order. These updates can be:

  • Payment accreditations that approve a previously pending order.
  • Subscription approvals (with or without payments) that approve a recurring order.
  • Subscription cancellations.
  • Payment refunds.

In MercadoPago, a subscription can become unlinked from its order when the user does not return to the store, so the order's gateway_key is not updated. See Subscriptions Flow with MercadoPago for the external_reference UUID fallback that resolves these cases.

Payment Flow​

Common checkout flow before any gateway-specific behavior:

  1. A user arrives at a publication page and buys individually or adds items to a cart.
  2. The customer proceeds to checkout and applies a coupon if available.
  3. Physical orders require a shipping address; Brazilian Reals purchases require the CPF field.
  4. A gateway that supports the cart currency is offered based on the priority defined in the gateways table.
  5. A pending order is created and the checkout process starts at the selected gateway.

After the order is created, all gateways follow the same universal pattern:

  1. The platform creates a payment intent (one-off) or a preapproval plan (subscription) at the gateway.
  2. The user is redirected to the gateway (init_point for one-off, preapproval URL for subscriptions).
  3. The user completes payment at the gateway and is returned to the store.
  4. On return, the platform updates the order status from the gateway response.

If the user does not return to the store, the order is reconciled by the asynchronous jobs documented in Payment Synchronization.

Per-gateway differences​

GatewayOne-offSubscriptionSession linkingNotes
MercadoPagoYesYesOrder UUID stored in session at checkout; gateway_key set when the user returns and the back URL hits receivePaymentFalls back to external_reference UUID when the user does not return; see Subscriptions Flow with MercadoPago
StripeYesYesOrder ID stored in session; gateway_key is the preapproval id created inside the preapproval planStandard flow
YunoYes (OTT, order created before payment)Yes (order created inside the recurring service)n/aSee Yuno Checkout Flow
PayUYes (legacy)n/an/aOne-off only; no refund or subscription path

Debugging​

When a payment, refund, or subscription behaves unexpectedly, activity_log is the first place to look. Each gateway connector logs its HTTP requests and responses (with secrets and sensitive data masked) to a dedicated channel. Actions applied by IPNs to payments and orders go to the shared payment_event channel across all gateways.

For gateway-specific channel names and detailed debug guidance, see each gateway's documentation:

Payment Synchronization​

See the Payment Synchronization documentation for detailed information on how payments are synchronized between gateways and publica.la, including automated jobs and processes.

X

Graph View