Appearance

Subscriptions ​

Subscriptions can be used to periodically charge customers by specifying the amount and scheduling information. With the PayPro Subscriptions API, you can set up recurring payments with fixed amounts.

Subscription periods and payments are automatically created and processed in the background at the specified frequency. The customer only needs to complete the payment process once, for the initial payment and all future payments are handled automatically.

You can monitor and manage the subscription activity directly in our Dashboard or by using Webhooks.

This guide is focused on to setup subscriptions with the API, but you can also use our no code solutions like the Payment page or other integrations.

Subscription flows ​

There are two flows to create a subscription:

  • Subscription with an Authorization Payment: The customer makes the first payment, and then a mandate is saved for future billing.

  • Subscription with an Existing Mandate: If you already have the customer’s mandate, you can start the subscription without an authorization payment.

We will explain both approaches in this guide.

Creating a Subscription ​

To create a Subscription, we need to do these three steps:

  1. Create a Customer: Use the Customer API to create a new customer or use an existing customer.
  2. Create a Subscription: Use the Subscriptions API to create a subscription for the customer.
  3. Listen for Webhook Events: Set up webhook listeners to handle events like subscription cancellations, payment confirmations, and chargebacks.

Create a Customer ​

The first step in setting up a subscription 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.

php
$customer = $paypro->customers->create(
  [
    'email' => 'customer@example.com',
    'first_name' => 'First name',
    'last_name' => 'Last name'
  ]
);
ruby
client = PayPro::Client.new('pp_...')

customer = client.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 set up a subscription by referencing the customer's unique ID.

Create a Subscription with an Authorization Payment ​

To create a subscription, use the Subscription API.

When creating a subscription, you need to provide:

  • customer: The ID of the customer who is subscribing.
  • description: A description of the subscription.
  • currency: The currency code for the subscription.
  • period: The settings for recurring billing, defining when new periods should be created and their amounts. The period parameter includes the following fields:
    • amount: The billing amount for each period.
    • vat: The VAT (tax) applied to each period.
    • interval: The frequency of the billing period (e.g., week, month).
    • multiplier: The number of intervals between each billing (e.g., every 1 month, every 3 months).

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.

php
$subscription = $paypro->subscriptions->create(
  [
    'customer' => 'CUSTOMER_ID',
    'description' => 'Subscription description',
    'currency' => 'EUR',
    'period' => [ 'amount' => 500, 'vat' => 21, 'interval' => 'month', 'multiplier' => 1 ]
  ]
);
ruby
subscription = client.subscriptions.create(
  customer: 'CUSTOMER_ID',
  description: 'Subscription description',
  currency: 'EUR',
  period: { amount: 500, vat: 21, interval: 'month', 'multiplier': 1 }
)

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:

php
$checkout_url = $subscription->links['checkout'];
header('Location: ' . $checkout_url);
exit();
ruby
# This assumes you are using Rails which has a redirect_to method
checkout_url = subscription.links['checkout']
redirect_to checkout_url

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 a Subscription with a Mandate ​

Recurring payments, like with a Subscription, require a Mandate from the Customer. A Mandate symbolizes the permission the Customer gave you to charge their payment method. When using the authorization flow we automatically create a Mandate object when the Customer pays, but you can also create mandates for your customers manually.

For instance, if you already have the customer's IBAN and account holder name, you can create a "direct-debit" mandate using the create Mandate API. This "direct-debit" mandate can than be used to create subscriptions without having to go through the authorization flow.

IMPORTANT

To create mandates you still the need permission from the customer. When creating a mandate make sure to clearly state that the customer will agree to additional charges. Communicating this clearly will also lead to less chargebacks and costs.

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

After creating the mandate, you can proceed to create the subscription. Since a mandate belongs to a customer, there's no need to specify a separate CUSTOMER_ID when creating the subscription this way.

php
$subscription = $paypro->subscriptions->create(
  [
    'mandate' => 'MANDATE_ID',
    'description' => 'Subscription description',
    'currency' => 'EUR',
    'period' => [ 'amount' => 500, 'vat' => 21, 'interval' => 'month', 'multiplier' => 1 ]
  ]
);
ruby
subscription = client.subscriptions.create(
  mandate: 'MANDATE_ID',
  description: 'Subscription description',
  currency: 'EUR',
  period: { amount: 500, vat: 21, interval: 'month', 'multiplier': 1 }
)

The subscription will be created and will become "active" immediately, with payments automatically processed based on the subscription period.

IMPORTANT

The first subscription period and the payment will be created immediately, unless you supply a different start_at date.

Set up subscription with a Trial Period ​

To offer a trial period for a subscription, use the first_period parameter when creating the subscription. This parameter defines the trial period and includes attributes such as:

  • amount: The charge amount for the trial period.
  • vat: The VAT (tax) applied to the trial period.
  • interval: The interval of the trial period (e.g., day, week, month).
  • multiplier: The number of intervals in the trial period (e.g., 1 month, 2 weeks).

Once the trial period ends, the subscription automatically transitions to the regular billing period specified in the period parameter.

php
$subscription = $paypro->subscriptions->create(
  [
    'mandate' => 'MANDATE_ID',
    'description' => 'Subscription description',
    'currency' => 'EUR',
    'first_period' => [ 'amount' => 100, 'vat' => 21, 'interval' => 'week', 'multiplier' => 2 ],
    'period' => [ 'amount' => 500, 'vat' => 21, 'interval' => 'month', 'multiplier' => 1 ]
  ]
);
ruby
subscription = client.subscriptions.create(
  mandate: 'MANDATE_ID',
  description: 'Subscription description',
  currency: 'EUR',
  first_period: { amount: 100, vat: 21, interval: 'week', 'multiplier': 2 },
  period: { amount: 500, vat: 21, interval: 'month', 'multiplier': 1 }
)

This setup enables new customers to try the service during the trial period, with regular billing starting automatically once the trial period ends.

The trial will not cancel automatically and you will have to cancel the subscription if you don't want the subsequent subscription periods to be created.

Start and Cancel Subscription Dates ​

You have the flexibility to specify when a subscription should start or be canceled:

  • start_at: Set this parameter to define the exact date and time when the subscription should begin. This allows you to schedule the subscription to start in the future, rather than immediately.

  • cancel_at: This parameter specifies the date when the subscription should be canceled. If cancel_at is not provided, the subscription will remain active until it is manually canceled.

Subscription Actions ​

You can manage the subscription's lifecycle with the following actions:

  • Pause Subscription: You can temporarily pause a subscription using the pause subscription endpoint. While paused, no new subscription periods will be created, and no payments will be processed.

  • Resume Subscription: After a subscription has been paused, you can reactivate it by calling the resume endpoint. This resumes the billing cycle and starts the next subscription period according to the original schedule.

  • Cancel Subscription: To permanently end a subscription, use the cancel endpoint. A canceled subscription will stop creating new periods, and no further payments will be processed. Once canceled, the subscription cannot be resumed.

Listen for Webhook Events ​

It is important to stay informed about changes to subscription statuses, such as when a user completes their first payment and the subscription becomes "active."

To track these events, we recommend implementing our Webhooks. Webhooks will notify you about changes to various resources, including subscriptions, created through our API. This allows you to take real-time actions based on subscription events.

For more details on how to set up and manage webhooks, visit the webhooks page.