Recurring Billing

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

This API integration includes 4 Steps

​

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

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

​

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

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:

​

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