Recurring Billing

Integrate the recurring billing APIs to automated your subscription payments

Recurring Billing APIs are the simplest way to start collecting your monthly or yearly subscription fees automatically.

This API integration includes 4 Steps

Create a Subscription Plan

The first step is to create a subscription plan with details and pricing.

Set Up Recurring Billing

Once the subscription plan is defined, set up recurring billing for the customer.

Present the Checkout UI

Present the checkout user interface to the customer for subscription confirmation.

Handle Payment Processing

After the customer confirms, handle payment processing and schedule recurring charges.

Step 1 - Create a subscription plan

A subscription plan consists of basic information like plan name, amount, and frequency. An example of a subscription plan could be “Spotify Premium” which is SGD 9.90 monthly.

HTTP Request

POST https://api.sandbox.hit-pay.com/v1/subscription-plan

Query Parameters

Mandatory fields are name, cycle and amount. Remember to include header Content-Type: application/x-www-form-urlencoded

Parameter	Description	Example
name	Plan name	Spotify Premium
description	The description of the subscription plan	Spotify Monthly Subscription
cycle	Billing frequency (weekly / monthly / yearly / custom / save_card). If cycle = custom then the user has to send the fields cycle_repeat and cycle_frequency	monthly
cycle_repeat	[This field is only applicable when cycle = custom] It’s the number of times the cycle will repeat.	4
cycle_frequency	[This field is only applicable when cycle = custom] It’s the frequency of the cycle [day / week / month / year]	week
currency	Currency related to the recurring billing	SGD
amount	Amount related to the recurring billing	9.90
reference	Arbitrary reference number that you can map to your internal reference number. This value cannot be edited by the customer	XXXX123

shell

curl --location --request POST 'https://api.sandbox.hit-pay.com/v1/subscription-plan' \
--header 'X-BUSINESS-API-KEY: meowmeowmeow' \
--header 'X-Requested-With: XMLHttpRequest' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'name=Spotify Premium' \
--data-urlencode 'description=Spotify Monthly Subscription' \
--data-urlencode 'currency=SGD' \
--data-urlencode 'amount=9.90' \
--data-urlencode 'cycle=monthly' \
--data-urlencode 'reference=spotify_premium_2022'

Response

{
    "id": "973ee344-6737-4897-9929-edbc9d7bf433",
    "name": "Spotify Premium",
    "description": "Spotify Monthly Subscription",
    "cycle": "monthly",
    "cycle_repeat": null,
    "cycle_frequency": null,
    "currency": "sgd",
    "amount": 9.90,
    "reference": "spotify_premium_2022",
    "created_at": "2022-09-12T14:19:26",
    "updated_at": "2022-09-12T14:19:26"
}

Step 2 - Create a recurring billing for the customer

Once your customer has decided to start the subscription this endpoint will create the recurring billing request.
Since this is a server-to-server communication, if you have a mobile or Web client that communicates with your REST API, you must have a new endpoint E.g. /create-subscription or reuse an existing endpoint. This endpoint will be responsible for making the recurring billing API call to hitpay.

HTTP Request

POST https://api.sandbox.hit-pay.com/v1/recurring-billing

Query Parameters

Mandatory fields are plan_id, customer_email, and start_date. If you would like to create a subscription without a plan, you need to send plan_id = null and the following mandatory fields: name, cycle, amount, customer_email, and start_date. Remember to include the header Content-Type: application/x-www-form-urlencoded.

Parameter	Description	Example
plan_id	Subscription plan id created from step 1	973ee344-6737-4897-9929-edbc9d7bf433
customer_email	Customer email	[e-mail]
customer_name	Customer name	Paul
start_date	Billing start date (YYYY-MM-DD) in SGT	2022-11-11
amount	By default, the amount from the subscription plan will be used. Use this parameter for discounts for customers.	7.90
currency	Currency related to the recurring billing	SGD
payment_methods[]	Choice of payment methods you want to offer the customer	giro, card
redirect_url	URL where hitpay redirects the user after the user enters card details and the subscription is active.	https://spotify.com/subscription-completed
reference	Arbitrary reference number for mapping purposes. Customer cannot edit this value.	XXXX123
webhook	Optional URL for hitpay to send a POST request on new charges or charging errors.	https://webhoo.site/test
send_email	Hitpay sends email receipts to the customer. Default value is false.	true
times_to_be_charged	Number of times to charge the customer.	3

Step 3 - Redirect customer to recurring billing page (One time set up)

Redirect the customer to the “url” value.

Once the customer completes the payment information it will be redirect to “redirect_url”

Step 4: Handle Successful Payment

Webhooks

HitPay will send a Webhook POST request when there is a new charge or if there is an error charging the card.
If you are using HitPay APIs to integrate into your app you must mark your order as paid ONLY after the webhook is received and validated.

1. Create an endpoint (E.g. /payment-confirmation/webhook) in your server that accepts POST requests. This request is application/x-www-form-urlencoded.
2. Validate the webhook data using your salt value
3. Return HTTP status code 200 to Hitpay
4. Mark your order as paid

sample webhook payload data

payment_id=974f65d6-88ea-42a0-a67a-15acafc4dc66&recurring_billing_id=9741164c-06a1-4dd7-a649-72cca8f9603a&amount=9.90&currency=sgd&status=succeeded&reference=cust_id_123&hmac=7690ff7ab7d88480a480b8be722f6dd12cc58f489da25c504dbe29c04b297418

Webhook fields

Following fields are sent with the webhook request:

Parameter	Description
payment_id	Payment ID
recurring_billing_id	Recurring billing request ID
amount	Amount related to the recurring billing
currency	Currency related to the recurring billing
status	Payment status (succeeded / failed)
reference	Arbitrary reference number that you have mapped during recurring billing request creation
hmac	Message Authentication code of this webhook request

Validate Webhook

Hitpay creates a list of all values from the key-value pairs that we send in the POST request and sort them in the order of their keys alphabetically. We then concatenate all these values together. We then use the HMAC-SHA256 algorithm to generate the signature. The HMAC key for the signature generation is the secret salt from your dashboard under API Keys.

public function generateSignatureArray($secret, array $args) 
    {   
        $hmacSource = [];        

        foreach ($args as $key => $val) {
            $hmacSource[$key] = "{$key}{$val}";
        }    

        ksort($hmacSource);

        $sig            = implode("", array_values($hmacSource));
        $calculatedHmac = hash_hmac('sha256', $sig, $secret); 

        return $calculatedHmac;
    }

Congrats! You have now successfully completed the recurring billing integration.

FAQs

What happens if an attached card associated with an active plan gets declined?

If an attached card associated with a plan gets declined on the scheduled charge date of the plan, the customer is immediately sent an email requesting them to update their card details using the link. At the same time, the merchant is also notified by email about the failed charge. If the customer fails to attach a valid card within 7 days from the failed charge date, the subscription will move to an inactive status.

When will a scheduled customer subscription be canceled?

The scheduled customer subscription will be canceled if the customer hasn’t entered their payment details by the billing start date.

If a customer's subscription is canceled, should I reuse the same one?

Yes, you can reuse the same subscription by calling the Update recurring billing API and setting a future start date.

Webhook Signature Mismatch?

Possible reasons for wrong hmac value generated

• Ensure that you are using the correct salt value from the correct environment (Sandbox or Production)
• Make sure NOT to include the hamc value when calculating the hmac
• Make sure all the values stated above are included in the payload including reference_number. Use an empty string if the value does not exist

Facing Invalid Business API Key Error

Possible reasons for this error:

• You are using a production key in the sandbox or a sandbox key in production. Make sure the API base URL is correct.
• You are missing headers. Ensure that you include both the ‘Content-Type’ and ‘X-Requested-With’ headers. Refer to this section again.

Product Checklist

Ensure the following before moving to production

• Change the base URL for all API calls to https://api.hit-pay.com/v1/
• Update API keys and Salt values from the production dashboard