Developer Docs

On-demand Subscriptions

This guide will show you how to create and work with On-demand Subscriptions.

We will cover these steps:

How do On-demand Subscriptions work
Creating an On-demand Subscription
Creating new installments

On-demand Subscriptions

On-demand Subscriptions are different from normal subscriptions. Normally, when you create a subscription in PayPro you have to supply information about the billing cycle.

For instance, if you want to do monthly payments for twelve installments, you have to supply us that information either by creating a Product in the PayPro dashboard or by creating a Product through the API.

After the subscription has been created, the PayPro system will automatically create new payments on the correct dates. This works fine for most subscriptions, but it is not flexible enough for some use cases:

Different amounts for each installment.
Different descriptions for each installment.
Irregular intervals between installments.

This is where On-demand Subscriptions come in. Instead of creating a product, you can create it with a single command. The On-demand Subscription will act like a normal subscription, but it will not automatically create new installments.

The merchant is responsible for the creation of new installments, which can be done through an API call.

This gives greater flexibility, but also means more work on your end.

Read futher to see how you can create On-demand Subscriptions and how to add installments.

Creating an On-demand Subscription

To create On-demand Subscriptions we need to use the create_payment command. It works almost the same as with normal create_payment calls, but we need to set periods_multiplier & periods_frequency to 0 so the API knows we want On-demand Subscriptions.

Ruby
PHP
Phyton

# Setup API client. Use your own API key here.
client = Paypro::Client.new('YOUR_API_KEY')
# Use the create_payment command
client.command = 'create_payment'
# Parameters that we need to use
client.params = {
  # Every create_payment needs an email.
  consumer_email: 'test@paypro.nl',
  # We set the amount of the first installment.
  amount: 500,
  # Pay method of the first installment. In this case we pay with iDEAL at the ING bank.
  pay_method: 'ideal/INGBNL2A',
  # Now we need to set periods_multiplier to 0.
  periods_multiplier: 0,
  # The parameter periods_frequency has to be 0 as well.
  periods_frequency: 0,
  # The customer has to approve the direct debits. Set this on true to let us know the customer approves.
  approve_machtiging: 'true'
}
# Execute the command and store the response.
response = client.execute

<?php
  // Setup API client. Use your own API key here.
  $client = new \Paypro\Client("YOUR_API_KEY");
  // Use the create_payment command
  $client->setCommand("create_payment");
  // Parameters that we need to use
  $client->setParams([
    // Every create_payment needs an email.
    "consumer_email" => "test@paypro.nl",
    // We set the amount of the first installment.
    "amount" => 500,
    // Pay method of the first installment. In this case we pay with iDEAL at the ING bank.
    "pay_method" => "ideal/INGBNL2A",
    // Now we need to set periods_multiplier to 0.
    "periods_multiplier" => 0,
    // The parameter periods_frequency has to be 0 as well.
    "periods_frequenc" => 0,
    // The customer has to approve the direct debits. Set this on true to let us know the customer approves.
    "approve_machtiging" => "true"
  ]);
  // Execute the command and store the response.
  $response = $client->execute();
?>

# Setup API client. Use your own API key here.
client = Client('YOUR_API_KEY')
# Use the create_payment command
client.setCommand('create_payment')
# Parameters that we need to use
client.setParams({
    # Every create_payment needs an email.
    'consumer_email': 'test@paypro.nl',
    # We set the amount of the first installment.
    'amount': 500,
    # Pay method of the first installment. In this case we pay with iDEAL at the ING bank.
    'pay_method': 'ideal/INGBNL2A',
    # Now we need to set periods_multiplier to 0.
    'periods_multiplier': 0,
    # The parameter periods_frequency has to be 0 as well.
    'periods_frequency': 0,
    # The customer has to approve the direct debits. Set this on true to let us know the customer approves.
    'approve_machtiging': 'true'
})
# Execute the command and store the response.
response = client.execute()

The API will respond with a JSON object. Use the payment_url in the hash to redirect the customer to the payment page.

{
  "payment_hash": "d12a2cbaafab029f9c156282f3857bb056a40217",
  "payment_url": "https://www.paypro.nl/betalen/d12a2cbaafab029f9c156282f3857bb056a40218"
}

This will result in an On-demand Subscription where the first installment will be paid with iDEAL.

Note that On-demand Subscriptions only work with direct debits. PayPal is not supported.

Create next installments

Now that we have an On-demand Subscription we want to create new installments. To do this we are going to use the create_recurring_payment command.

This command takes an amount and a sale_id parameter. The sale_id will be the ID of the On-demand Subscription and the amount will be the amount of the next installment.

In the previous section, we got the payment_hash back from the create_payment API call. With the payment_hash we can get the sale_id by doing a get_sale API call. Check the Payments Quickstart to see how to use the get_sale command.

Once you have the sale_id you can create new installments.

Note that currently, you cannot set the date of an installment. When you create an installment, it will be processed within a day.

Ruby
PHP
Phyton

# Setup API client. Use your own API key here.
client = Paypro::Client.new('YOUR_API_KEY')
# Use the create_recurring_payment command.
client.command = 'create_recurring_payment'
# Parameters that we need to use
client.params = {
  # Sale ID of the On-demand Subscription.
  sale_id: 123456,
  # Amount of the next installment. In this instance 5 euros.
  amount: 500,
  # Optional, we can change the description.
  description: 'Second installment of subscription 123456',
  # Optional, we can change the IBAN of the subscription.
  # For the next installments we will use this IBAN.
  consumer_accountno: 'NL52RABO0504739492'
}
# Execute the command and store the response.
response = client.execute

<?php
  // Setup API client. Use your own API key here.
  $client = new \Paypro\Client("YOUR_API_KEY");
  // Use the create_recurring_payment command.
  $client->setCommand("create_recurring_payment");
  // Parameters that we need to use
  $client->setParams([
    // Sale ID of the On-demand Subscription.
    "sale_id" => 123456,
    // Amount of the next installment. In this instance 5 euros.
    "amount" => 500,
    // Optional, we can change the description.
    "description" => "Second installment of subscription 123456",
    // Optional, we can change the IBAN of the subscription.
    // For the next installments we will use this IBAN.
    "consumer_accountno" => 'NL52RABO0504739492'
  ]);
  // Execute the command and store the response.
  $response = $client->execute();
?>

# Setup API client. Use your own API key here.
client = Client('YOUR_API_KEY')
# Use the create_recurring_payment command.
client.setCommand('create_recurring_payment')
# Parameters that we need to use
client.setParams({
    # Sale ID of the On-demand Subscription.
    'sale_id': 123456,
    # Amount of the next installment. In this instance 5 euros.
    'amount': 500,
    # Optional, we can change the description.
    'description': 'Second installment of subscription 123456',
    # Optional, we can change the IBAN of the subscription.
    # For the next installments we will use this IBAN.
    'consumer_accountno': 'NL52RABO0504739492'
}
# Execute the command and store the response.
response = client.execute()

The API will respond with a JSON object. This contains information about the created installment.

{
  // Number of the installment. This is the second installment of the subscription.
  "sequence_number": 2,
  // Unique ID of the installment
  "period_id": 234567,
  // Mandate of the subscription. This is what the customers see.
  "mandate_id": "I-123456",
  // ID of the subscription
  "sale_id": 123456
}

What’s next

That’s all you need to create On-demand Subscriptions! Things like postbacks and invoices will work the same as with normal subscriptions. If you want more info about these subjects check the other guides.

Postbacks

Let’s go

API Reference

Let’s go

Support

Would you like additional support or do you have questions? Contact us.