Subscriptions

Subscriptions

A subscription bills a customer on a plan's schedule. Creating one opens a first invoice whose payment intent the customer pays like any other; that payment also saves their card for later cycles. Its status then changes by webhook: incomplete until the first payment, active while invoices are paid, past due or unpaid when they are not, and cancelled. Subscriptions must be enabled on the PayMongo account, and they take cards and Maya only.

Read the Plans & Subscriptions docs

Every demonstration here makes a real PayMongo API call in test mode. Nothing is simulated, and no real money moves.

Create customer

Create the fictional customer to subscribe. Every customer Step is in the Customers scenario.

PHP
use Luigel\Paymongo\Facades\Paymongo;

$customer = Paymongo::customers()->create(
    attributes: [
        'first_name' => '••••',
        'last_name' => '••••',
        'email' => '••••',
        'phone' => '••••',
        'default_device' => 'email',
    ],
);

Create plan

Create the plan to subscribe to, or pick one already created. Every plan Step is in the Plans scenario.

PHP
use Luigel\Paymongo\Facades\Paymongo;

$plan = Paymongo::plans()->create(
    attributes: [
        'name' => 'Playground Monthly',
        'description' => 'Laravel PayMongo Playground demo plan',
        'amount' => 29900,
        'currency' => 'PHP',
        'interval' => 'monthly',
        'interval_count' => 1,
    ],
);

Create subscription

Subscribe a customer to a plan. The package takes the two identifiers as its arguments rather than an attributes array. The subscription starts incomplete, with a first invoice whose payment intent the Playground records so it can be paid next.

Test mode: PayMongo returns an error when subscriptions are not enabled on the account. The first payment must be made within 24 hours, or the subscription becomes incomplete_cancelled.

PHP
use Luigel\Paymongo\Facades\Paymongo;

$subscription = Paymongo::subscriptions()->create(
    customerId: '{customer id}',
    planId: '{plan id}',
);

Create card payment method

Create the card that pays the first invoice, or that the subscription switches to.

PHP
use Luigel\Paymongo\Facades\Paymongo;

$paymentMethod = Paymongo::paymentMethods()->create(
    attributes: [
        'type' => 'card',
        'details' => [
            'card_number' => '••••4345',
            'exp_month' => '••',
            'exp_year' => '••',
            'cvc' => '•••',
        ],
        'billing' => [
            'name' => '••••',
            'email' => '••••',
            'phone' => '••••',
        ],
    ],
);

Make the initial payment

Attach a card to the payment intent of the subscription's first invoice: pick the one the subscription's summary names as its initial payment intent. Once it succeeds, the subscription becomes active by webhook: keep the subscription's Step open to watch its events arrive.

Test mode: Card vaulting must be enabled on the account for the card to be saved against the customer. A 3D Secure card leaves the intent awaiting_next_action with a redirect URL to authorize it.

PHP
use Luigel\Paymongo\Facades\Paymongo;

$paymentIntent = Paymongo::paymentIntents()->attach(
    id: '{payment_intent id}',
    paymentMethodId: '{payment_method id}',
    returnUrl: 'https://paymongo.rigelkentcarbonel.com/scenarios/subscriptions',
);

Retrieve subscription

Fetch a subscription to see its status, latest invoice, and next billing date.

PHP
use Luigel\Paymongo\Facades\Paymongo;

$subscription = Paymongo::subscriptions()->retrieve(
    id: '{subscription id}',
);

List subscriptions

Fetch one cursor page of subscriptions.

Test mode: PayMongo lists every subscription on the account. The Playground shows only the ones created through it.

PHP
use Luigel\Paymongo\Facades\Paymongo;

$subscription = Paymongo::subscriptions()->list(
    params: [
        'limit' => 20,
    ],
);

Change plan

Move a subscription onto another plan. The current cycle is billed at the old plan's rate; the new plan applies from the next cycle.

PHP
use Luigel\Paymongo\Facades\Paymongo;

$subscription = Paymongo::subscriptions()->changePlan(
    id: '{subscription id}',
    planId: '{plan id}',
);

Change payment method

Switch the card future cycles are charged to. PayMongo authorizes a small amount on the new card through a setup intent, then cancels it. The Playground records the setup intent, so the Payment intents scenario can retrieve it.

Test mode: The customer must authenticate the new card. When the setup intent is awaiting_next_action, open its URL to authorize it on the PayMongo test page.

PHP
use Luigel\Paymongo\Facades\Paymongo;

$subscription = Paymongo::subscriptions()->changePaymentMethod(
    id: '{subscription id}',
    paymentMethodId: '{payment_method id}',
    redirectUrl: 'https://paymongo.rigelkentcarbonel.com/scenarios/subscriptions',
);

Trigger a test billing cycle

Start the next billing cycle now instead of on its date. This operation exists in test mode only. The package returns nothing, so the new invoice and its payment arrive by webhook, or by retrieving the subscription.

Test mode: PayMongo's reference does not say which subscription states a test cycle accepts. Make the initial payment first; any error PayMongo returns is shown here as it came.

PHP
use Luigel\Paymongo\Facades\Paymongo;

$subscription = Paymongo::subscriptions()->triggerTestCycle(
    id: '{subscription id}',
);

Cancel subscription

Cancel a subscription immediately. A reason is required: too_expensive, missing_features, switched_service, unused, or other. The package also accepts its CancellationReason enum.

Test mode: Invoices already open when the subscription is cancelled stay collectible.

PHP
use Luigel\Paymongo\Facades\Paymongo;

$subscription = Paymongo::subscriptions()->cancel(
    id: '{subscription id}',
    reason: '',
);