On-demand subscriptions

On-demand subscriptions allow you to charge customers based on your own schedule rather than a fixed billing cycle like monthly or yearly plans. Payments and subscription periods are not generated automatically, giving you full control over the billing frequency and amounts. This model is particularly useful for usage-based services, where traditional recurring billing isn’t ideal.

You can monitor and manage the subscription activity directly in our Dashboard.

We will now discuss how you can create an on-demand subscription with our Subscriptions API.

Steps to create the on-demand subscription

1. Create a Customer: Use the Customer API to create a new customer or use an existing customer.
2. Create a Mandate: Use the Mandate API to create a new mandate or use an existing mandate.
3. Create a Subscription: Use the Subscriptions API to create a subscription for the customer and specify "scheduling": "manual".
4. Create next Subscription Periods: Use the Subscription periods API to create a next period for the subscription.

Create a Customer

The first step is to create a Customer. This Customer object represents the entity (person or company) that will be billed. You can create a Customer using the Customer API.

$customer = $paypro->customers->create(
  [
    'email' => 'customer@example.com',
    'first_name' => 'First name',
    'last_name' => 'Last name'
  ]
);

Once the Customer object is created, you can use it to create a mandate by referencing the customer's unique ID.

Create a Mandate

A Mandate symbolizes the permission the Customer gave you to charge their payment method. For example, if you already have the customer’s IBAN and account holder name, you can manually create a "direct-debit" mandate using the create Mandate API. Once created, this "direct-debit" mandate can be used to set up and process recurring payments.

$payment = $paypro->mandates->create(
  [
    'customer' => 'CUSTOMER_ID',
    'pay_method' => 'direct-debit',
    'iban' => 'IBAN',
    'account_holder_name' => 'Account Holder Name'
  ]
);

Create an On-demand Subscription

After creating the mandate, you can proceed with setting up the on-demand subscription. As the mandate is already linked to a specific customer, there’s no need to include a separate CUSTOMER_ID.

When creating the on-demand subscription, ensure that the request body includes "scheduling": "manual". Additionally, provide the following parameters:

• mandate – The unique ID of the mandate.
• description – A brief description.
• currency – The currency for the subscription.
• first_period – An object containing:
  • amount: The charge amount for the first period.
  • vat: The VAT (tax) applied to the trial period.

Since future billing periods and payments are managed manually, you do not need to specify the period’s multiplier or interval.

$subscription = $paypro->subscriptions->create(
  [
    'mandate' => 'MANDATE_ID',
    'description' => 'Subscription description',
    'currency' => 'EUR',
    'scheduling' => 'manual',
    'first_period' => [ 'amount' => 500 ]
  ]
);

The subscription will be created and will become "active" immediately.

Create a Subscription with an Authorization Payment

If the customer's mandate is unknown, you can create an on-demand subscription using an Authorization Payment. In this process, the customer completes the first payment, which automatically generates and saves a mandate for future billing.

When creating a subscription, you need to specify "scheduling": "manual" and provide:

• customer: The ID of the customer who is subscribing.
• description: A description of the subscription.
• currency: The currency code for the subscription.
• first_period - An object containing:
  • amount: The billing amount for the first period.
  • vat: The VAT (tax) applied to the period.

Optionally, you can specify additional payment details, such as return_url - the URL to which the customer will be redirected after the payment is processed. More details are available here.

$subscription = $paypro->subscriptions->create(
  [
    'customer' => 'CUSTOMER_ID',
    'description' => 'Subscription description',
    'currency' => 'EUR',
    'scheduling' => 'manual',
    'first_period' => [ 'amount' => 500 ]
  ]
);

Once the subscription object is created, you can redirect the customer to the checkout URL to complete the first payment. This checkout link is available in the created subscription object:

$checkout_url = $subscription->links['checkout'];
header('Location: ' . $checkout_url);
exit();

When redirecting the customer to the checkout URL, they will leave your site. Depending on the payment method, they may need to provide additional information and could be directed to their bank or card issuer to authenticate the transaction.

After the customer completes the payment, they will be redirected either to a PayPro hosted success page or to the return_url specified in the payment_details. The subscription status will become "active" once the payment is successfully processed.

Create next subscription period

To create the next period for the subscription you can use Subscription period API. Note that the next period can only be created for an active subscription.

$subscription = $paypro->subscriptions->get('SUBSCRIPTION_ID');
$subscription_period = $subscription->createSubscriptionPeriod(['amount' => 5000]);

Once a period is created, the payment is automatically created and processed using the subscription's mandate.

Difference between on-demand subscription and recurring payments

Both Recurring Payments and On-Demand Subscriptions enable businesses to charge customers automatically without a fixed schedule.

• On-Demand Subscriptions provide full control over billing cycles. You can monitor and manage subscription activity in our Dashboard, as well as pause, resume, or cancel subscriptions. Each subscription consists of subscription periods and payments, allowing for a structured but flexible billing approach.

• Recurring Payments, on the other hand, are standalone payment transactions without subscription periods. While they are processed automatically, they do not include built-in subscription management features.