QorePay logo
QorePay logo

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.

QorePay supports two payment methods for automated recurring subscription charges:

  1. Debit/Credit Card
  2. Bank account direct debit

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, QorePay 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:

  1. Set the invoice_send_receipt to false when creating a billing template via the API to suppress automated sending of receipt notifications to customers.
  2. Set send_invoice_on_charge_failure in add_subscribercall 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:
  • Price:
  • 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

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

cURL


  curl -X 'POST'
    'https://gate.qorepay.com/api/v1/billing_templates/'
    -H 'Authorization: {{Your QorePay 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"
        }
      ],
       "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 likesubscription_period when creating it and add BillingTemplateClientobjects 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


  curl -X 'POST'  
    'https://gate.qorepay.com/api/v1/billing_templates/{{billing_template_id}}/add_subscriber/'
    -H 'Authorization: Bearer  {{Your QorePay 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.

JSON


  {"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.

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

For subscriptions, you can edit ( PATCH /billing_templates/{id}/clients/{id}/) this status between active and subscription_pausedvalues 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.

JSON


  {
    "status": "subscription_paused"
  }

ON THIS PAGE