Subscription Billing

Customer Starts a Subscription

The customer adds a subscription product to their cart in FluentCart and proceeds to checkout. When they select Przelewy24, the checkout UI shows only card payment methods with a notice:

Subscription requires card payment.

Transaction Registration with Card Channel

The plugin registers the transaction with Przelewy24 using channel: 1 (cards only). This ensures the customer pays with a card that can be tokenized for future charges.

Payment and Card Tokenization

The customer is redirected to Przelewy24's payment page, enters their card details, and completes the payment. Przelewy24 processes the charge and sends the IPN notification back to your site.

Card Info Retrieval

After the IPN confirms a successful payment, the plugin calls the Przelewy24 card info endpoint (GET /api/v1/card/info/{orderId}) to retrieve:

• refId — the card reference ID used for future charges (the tokenized card identifier)
• mask — the masked card number (e.g., 4444****4444)
• cardType — the card brand (Visa, Mastercard, etc.)
• cardDate — the card expiration date

These values are stored as subscription meta:

First Renewal Scheduled

The plugin sets the subscription's vendor_subscription_id to p24_sub_{id} and schedules the first renewal using Action Scheduler, based on FluentCart's billing interval.

Action Scheduler Fires

At the scheduled time, Action Scheduler runs the fchub_p24_process_renewal hook with the subscription ID. The plugin loads the subscription and validates it:

• Subscription must exist
• Status must be active, trialing, or failing
• There must be remaining bill times (not end-of-term)
• A card refId must be stored on the subscription

Transaction Registration with methodRefId

The plugin registers a new transaction with Przelewy24, this time including the methodRefId parameter — the stored card reference ID from the initial payment. This tells P24 to charge the previously tokenized card.

POST /api/v1/transaction/register
{
  "sessionId": "new-uuid-for-this-renewal",
  "amount": 10000,
  "currency": "PLN",
  "methodRefId": "stored-card-ref-id",
  "channel": 1,
  ...
}

A pending renewal session ID is stored on the subscription meta (_p24_pending_renewal_session) so the IPN handler can route the notification correctly.

Card Charge

The plugin calls the card charge endpoint (POST /api/v1/card/charge) with the token received from the registration. This initiates the charge asynchronously — the actual result comes via IPN.

IPN Confirms Renewal

When the charge succeeds, Przelewy24 sends an IPN notification. The plugin's IPN handler detects that the session belongs to a pending renewal (by matching _p24_pending_renewal_session), verifies the payment, and records it through FluentCart's SubscriptionService::recordRenewalPayment().

Next Renewal Scheduled

After a successful renewal, the plugin:

1. Resets the retry counter to 0
2. Calculates the next billing date using FluentCart's guessNextBillingDate()
3. Schedules the next renewal via Action Scheduler

If the subscription has reached its end-of-term (no more required bill times), no further renewal is scheduled.