Guides

Recurring billing

Overview

A subscription is a product where a customer must pay a subscription price to access the product or service, and they get billed on a recurring schedule (monthly, yearly etc.). Payment on these products needs to be processed every month, and the terms of payment (longevity, billing frequency, etc.) must be defined upfront.

Revio supports three payment methods for automated recurring subscription charges:

  1. Credit card
  2. Debit order and Debicheck
  3. Recurring instant EFT

How it works

To use our subscription features, create a billing template via our API or your dashboard. Then subscribe a customer to the billing template.

Once the client's recurring payment method has been tokenised, we'll handle subsequent charges when the billing is due.

📘

If a charge to the customer's preferred recurring payment method fails on the billing date, Revio will automatically send the customer an email to inform them of the failure. The customer will have the option of paying the invoice due through available payment methods.

We'll send you a webhook notification whenever a charge succeeds or fails or when a subscription is cancelled. On successful charge, your customer will receive an email receipt confirming the payment.

To be in full control of customer messaging, please note the following:

  • Set the invoice_send_receipt to false when creating a billing template via the API to suppress
    automated sending of receipt notifications to customers.

  • Set send_invoice_on_charge_failure in add_subscriber call to false to control whether the invoice will
    be sent via email when a charge fails.

Creating a subscription billing template via API

BillingTemplates generate Purchase objects that can be used to issue one-time or recurring invoices.

It does so by copying over its' PurchaseDetails, one of its BillingTemplateClient-s and generating other fields from BillingTemplate's fields as necessary into a new Purchase object.

To create a subscription you will require the following minimum fields:

  • Title: Name of the billing template
  • Currency: Currency in which your customer will be billed
  • Name: Name of the product or service you are sellling
  • Price
  • Brand_id
  • Is_subscription: To differentiate between once-off and recurring invoices
  • Subscription_active: Whether the subscription billing template is active or not
  • Subscription_period_units: Defines how often are the subscription Purchases generated. E.g. Weekly/monthly
  • Subscription_period: Defines how often invoices are generated and is used together with subscription_period_units. E.g. 1 = Once a month
  • Subscription_due_period: Period after an invoice is generated that it is due. E.g. Days, weeks
  • Subscription_due_period_units: E.g. 1 = invoice will is due in one day
  • Subscription_charge_period_end: Determines whether an invoice is generated in the beginning or end of the billing cycle
  • Subscription_trial_periods: Skips specified period and only starts invoicing your customer. E.g. freemium package
  • Force_recurring: Forces the save of a token when a customer pays with a recurring payment method

Once you've got these details, call our create billing template endpoint to create a new payment plan.


curl -X 'POST' \
  'https://gate.reviopay.com/api/v1/billing_templates/' \
  -H 'Authorization: Bearer Your Revio Bearer token' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "purchase": {
    "currency": "str",
    "products": [
      {
        "name": "string",
        "quantity": "1",
        "price": 0,
        "discount": 0,
        "tax_percent": "0",
        "category": "string"
      }
    ],
    "language": "Default value is controlled in Company -> Brand section of merchant portal separately per each Brand used (default value, if no changes are made, is `en`). Brand to be used with corresponding Purchase/BillingTemplate specified using brand_id.",
    "notes": "string",
    "debt": 0,
    "subtotal_override": null,
    "total_tax_override": null,
    "total_discount_override": null,
    "total_override": null,
    "request_client_details": [],
    "timezone": "Europe/Oslo",
    "due_strict": false,
    "payment_method_details": {
      "direct_debit": {
        "profile_code": "string",
        "abbreviated_name": "string",
        "account_number": "string"
      }
    }
  },
  "brand_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "title": "string",
  "is_subscription": true,
  "invoice_issued": "2020-04-30",
  "invoice_due": 1619740800,
  "invoice_skip_capture": false,
  "invoice_send_receipt": false,
  "subscription_period": 1,
  "subscription_period_units": "months",
  "subscription_due_period": 7,
  "subscription_due_period_units": "days",
  "subscription_charge_period_end": false,
  "subscription_trial_periods": 0,
  "subscription_active": false,
  "force_recurring": false
}'

If is_subscription is true, it is considered a subscription's BillingTemplate.

You will need to specify subscription_* fields like subscription_period when creating it and add BillingTemplateClient objects to its billing cycle (POST /billing_templates/{id}/add_subscriber/).

After that, the clients will receive recurring invoices (that will be paid for automatically if the client saves their recurring payment method details) according to the BillingTemplate settings you have specified.

If is_subscription is false, this BillingTemplate is used to send one-time invoices. After creating it and specifying invoice_* fields, use POST /billing_templates/{id}/send_invoice/ request to send the actual invoices. BillingTemplateClients for non-subscription BillingTemplates are not saved.

Adding a customer to a billing template

To add a customer to a subscription billing template, use the add subscriber endpoint, and specify the billing template id when charging the customer for the first time. 

curl -X 'POST' \
  'https://gate.reviopay.com/api/v1/billing_templates/3fa85f64-5717-4562-b3fc-2c963f66afa6/add_subscriber/' \
  -H 'Authorization: Bearer Your Revio Bearer token' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "client_id": "b79d3df6-2f69-4426-acee-eda049d83e18",
}'

Dynamic customer billing amounts

Sometimes you want to charge customers on the same plan different amounts. You can do this by adding an override in the add subscriber call to set purchase terms specific to a customer.

Customers without the override will continue to be billed as per the billing template billing terms.

{"invoice_override": {
        "debt": 0,
        "subtotal_override": 575,
        "total_tax_override": null,
        "total_discount_override": "15.00",
        "total_override": 575,
        "products": [
            {
                "name": "Special price plan",
                "price": 500,
                "quantity": "1.0000",
                "discount": 0,
                "tax_percent": "15.00",
            },
        ]
    }}

Activating, amending or pausing subscription billing templates

Both billing template and subscriber billing details can be amended by using the PUT Billing template and PATCH Subscriber end-points, respectively.

For subscriptions, you can edit (PATCH /billing_templates/{id}/clients/{id}/) this status between active and subscription_paused values to pause the client's subscription.

Paused subscriptions run as normal, except for purchases not being created and invoices sent for them. It means that if you pause a BillingTemplateClient's monthly subscription cycle a day before the billing date, the next day, the invoice will not be issued; but, if you unpause the client a day after the planned billing would have taken place, the planned billing in a month (minus one day) will happen as usual.

{
  "status": "subscription_paused"
}

Updated over 1 year ago