Subscription Manager API

PayHere Subscription Manager API lets you view, retry & cancel your subscription customers programmatically you subscribed from Recurring API. If you're new to Recurring API, please refer Recurring Billing introduction first.

Subscription Manager API is a RESTful API where you can directly send a HTTP Request with GET/POST parameters to an API end point. You will get the results directly in the HTTP Response for the requests. This API is secured with OAuth authentication & therefore you need first generate a pair of App ID & App Secret from your PayHere account, derive an Authorization code from them & finally retrieve an Access Token from the Authorization code in order to consume the Subscription API.

Please follow the below steps.

1. Create an API Key

Sign in to your PayHere account & go to Settings > API Keys section
Click 'Create API Key' button & enter an app name & comma seperated domains to whilelist
Tick the permission 'Automated Charging API'
Click 'Save API Key' button to create the app
Once the app is created click 'View Credentials' button in front of the created record
Copy the 'App ID' & 'App Secret' values

2. Generate an Authorization code

Go to a Base64 encoding site such as https://www.base64encode.net/
Paste the App ID & App Secret you copied from Step 1 above, separated by a colon (:) mark. eg. 4OVx33RVOPg4DzdZUzq4A94D2:8n4VCj25MXp4JLDFyvsE9h4a8qgbPaZUI4JEWK4FCvop
Click 'Encode' button & copy the base64 encoded value. This is your Authorization code.

or if you are using OAuth library, you may use BASIC authorization technique by passing App ID & App Secret directly.

3. Retrieve an Access Token

If you don't already have a valid Access Token, you can retrieve one by consuming following API end point.

Request URL

Sandbox - https://sandbox.payhere.lk/merchant/v1/oauth/token
Live    - https://www.payhere.lk/merchant/v1/oauth/token

Authorization: Basic <Authorization_code>

eg. Authorization: Basic NE9WeDMzUlZPUGc0RHpkWlV6cTRBOTREMjo4bjRWQ2oyNU1YcDRKTERGeXZzRTloNGE4cWdiUGFaVUk0SkVXSzRGQ3ZvcA==

Body

grant_type: client_credentials

The response for the above request will looks like following.

Response

{
    "access_token": "cb5c47fd-741c-489a-b69e-fd73155ca34e",
    "token_type": "bearer",
    "expires_in": 599,
    "scope": "SANDBOX"
}

Retrieve the access_token from the above response.

4. Consume API Endpoints

Consume the following Subscription API endpoints with a valid access_token to manage the subscriptions programmatically on demand.

Attention: Please note that in Live environment, this API can be consumed only from the allowed domains you white-listed when creating the Business App in Step 1.

a. View all subscriptions

Request URL (GET)

Sandbox - https://sandbox.payhere.lk/merchant/v1/subscription
Live    - https://www.payhere.lk/merchant/v1/subscription

Header

Authorization: Bearer <access_token>
Content-Type: application/json

eg. Authorization: Bearer cb5c47fd-741c-489a-b69e-fd73155ca34e

The response for the above request will looks like following.

Response

{
    "status": 1,
    "msg": "Found 1 subscriptions",
    "data": [
        {
            "subscription_id": 420075032251,
            "order_id": "Order0003",
            "date": "2018-10-04 20:24:52",
            "description": "Book reading Subscription",
            "recurring": "Charged every month for 3 years",
            "status": "ACTIVE",
            "amount": 100,
            "currency": "LKR",
            "customer": {
                "fist_name": "Saman",
                "last_name": "Kumara",
                "email": "[email protected]",
                "phone": "+94712345678",
                "delivery_details": {
                    "address": "1, Galle Road",
                    "city": "Colombo",
                    "country": ""
                }
            },
            "amount_detail": {
                "currency": "LKR",
                "gross": 200,
                "fee": 36.6,
                "net": 163.4,
                "exchange_rate": 1,
                "exchange_from": "LKR",
                "exchange_to": "LKR"
            },
            "payment_method": {
                "method": "VISA",
                "card_customer_name": "Saman Kumara",
                "card_no": "************4564"
            },
            "items": [
                {
                    "name": "Book reading Subscription",
                    "quantity": 1,
                    "currency": "LKR",
                    "unit_price": 100,
                    "total_price": 100
                },
                {
                    "name": "Startup Fee",
                    "quantity": 1,
                    "currency": "LKR",
                    "unit_price": 100,
                    "total_price": 100
                }
            ]
        }
    ]
}

The top level status is used in every call to identify whether the operation is success or not.

1 - success
-1 - failed. Refer msg element for more details

You will get a list of subscriptions under data element. Every subscription is identified using the unique ID which is the value of data[i].subscription_id. In above example subscription_id is 420075032251

Subscription status codes (data[i].status)

ACTIVE - Subscription is active and will charge in future.
COMPLETED - Subscription is completed. No future charging will be happen.
FAILED - Subscription was continuously failed and will not try further by PayHere

b. View payments of a subscription

You need subscription_id retrieved from above call to access the payments.

Request URL (GET)

Sandbox - https://sandbox.payhere.lk/merchant/v1/subscription/{subscription_id}/payments
Live    - https://www.payhere.lk/merchant/v1/subscription/{subscription_id}/payments

eg: https://sandbox.payhere.lk/merchant/v1/subscription/420075032251/payments

Header

Authorization: Bearer <access_token>
Content-Type: application/json

eg. Authorization: Bearer cb5c47fd-741c-489a-b69e-fd73155ca34e

The response for the above request will looks like following.

Response

{
    "status": 1,
    "msg": "Found 2 payments",
    "data": [
        {
            "payment_id": 320025023469,
            "order_id": "Order0003",
            "date": "2018-10-04 20:24:52",
            "description": "Book reading Subscription",
            "status": "RECEIVED",
            "currency": "LKR",
            "amount": 200,
            "customer": {
                "fist_name": "Saman",
                "last_name": "Kumara",
                "email": "[email protected]",
                "phone": "+94712345678",
                "delivery_details": {
                    "address": "1, Galle Road",
                    "city": "Colombo",
                    "country": ""
                }
            },
            "amount_detail": {
                "currency": "LKR",
                "gross": 200,
                "fee": 36.6,
                "net": 163.4,
                "exchange_rate": 1,
                "exchange_from": "LKR",
                "exchange_to": "LKR"
            },
            "payment_method": {
                "method": "VISA",
                "card_customer_name": "Saman Kumara",
                "card_no": "************4564"
            },
            "items": [
                {
                    "name": "Book reading Subscription",
                    "quantity": 1,
                    "currency": "LKR",
                    "unit_price": 100,
                    "total_price": 100
                },
                {
                    "name": "Startup Fee",
                    "quantity": 1,
                    "currency": "LKR",
                    "unit_price": 100,
                    "total_price": 100
                }
            ]
        },
        {
            "payment_id": 320025023470,
            "order_id": "Order0003",
            "date": "2018-10-04 20:25:52",
            "description": "Book reading Subscription",
            "status": "RECEIVED",
            "currency": "LKR",
            "amount": 100,
            "customer": {
                "fist_name": "Saman",
                "last_name": "Kumara",
                "email": "[email protected]",
                "phone": "+94712345678",
                "delivery_details": {
                    "address": "1, Galle Road",
                    "city": "Colombo",
                    "country": ""
                }
            },
            "amount_detail": {
                "currency": "LKR",
                "gross": 100,
                "fee": 34.3,
                "net": 65.7,
                "exchange_rate": 1,
                "exchange_from": "LKR",
                "exchange_to": "LKR"
            },
            "payment_method": {
                "method": "VISA",
                "card_customer_name": "Saman Kumara",
                "card_no": "************4564"
            },
            "items": [
                {
                    "name": "Book reading Subscription",
                    "quantity": 1,
                    "currency": "LKR",
                    "unit_price": 100,
                    "total_price": 100
                }
            ]
        }
    ]
}

c. Retry subscription

If you need to retry a failed subscription this method can be used. You need subscription_id to acess the subscription which need to be retried

Request URL (POST)

Sandbox - https://sandbox.payhere.lk/merchant/v1/subscription/retry
Live    - https://www.payhere.lk/merchant/v1/subscription/retry

Header

Authorization: Bearer <access_token>
Content-Type: application/json

eg. Authorization: Bearer cb5c47fd-741c-489a-b69e-fd73155ca34e

Body

{
  "subscription_id" : 420075032251
}

The response for the above request will looks like following.

Success Response

{
    "status": 1,
    "msg": "Recurring payment charged successfully",
    "data": null
}

Error response

{
    "status": -1,
    "msg": "Subscription is not eligible for retrying",
    "data": null
}

Possible reasons for this error are

Subscriptions has not failed previously
Subscription is already cancelled.

d. Cancel subscription

If you need to cancel a subscription this method can be used. You need subscription_id to acess the subscription which need to be cancelled.

Request URL (POST)

Sandbox - https://sandbox.payhere.lk/merchant/v1/subscription/cancel
Live    - https://www.payhere.lk/merchant/v1/subscription/cancel

Header

Authorization: Bearer <access_token>
Content-Type: application/json

eg. Authorization: Bearer cb5c47fd-741c-489a-b69e-fd73155ca34e

Body

{
  "subscription_id" : 420075032251
}

The response for the above request will looks like following.

Success Response

{
    "status": 1,
    "msg": "Successfully cancelled the subscription",
    "data": null
}

Error responses

{
    "status": -1,
    "msg": "Subscription is already cancelled.",
    "data": null
}

Subscription is already cancelled and cannot be cancelled again

{
    "status": -1,
    "msg": "Subscription is already completed.",
    "data": null
}

A completed subscription cannot be cancelled as the subscription has finished charging all of its recurring payments.

Attention:

You need to follow Steps 1 & 2 only one time to generate an Authorization code for your app
You need to follow Step 3 & retrieve a new Access Token only if your current Access Token is expired
If you already have a valid Access Token, you can directly make the request using the same Access Token

5. Error Handling

Error messages may returned for above APIs end points due to the following reasons. You need to identify them & handle them properly in your application.

Invalid Access Token

{
    "error": "invalid_token",
    "error_description": "Invalid access token: e291493a-99a5-4177-9c8b-e8cd18ee9f85"
}

Access Token Expired

{
    "error": "invalid_token",
    "error_description": "Access token expired: cb5c47fd-741c-489a-b69e-fd73155ca34e"
}

Invalid API Authorization (eg. Consuming through a not allowed domain, ect.)

{
    "status": -2,
    "msg": "Authentication error",
    "data": null
}

Subscription API - PayHere Knowledge Base

Still need help? Get in touch!

Last updated on 20th Jan 2023

Main articles

Links & Buttons

Api & Mobile Sdk

Shopping Cart Plugins

Subscription Manager API

1. Create an API Key

2. Generate an Authorization code

3. Retrieve an Access Token

Request URL

Header

Body

Response

4. Consume API Endpoints

a. View all subscriptions

Request URL (GET)

Header

Response

b. View payments of a subscription

Request URL (GET)

Header

Response

c. Retry subscription

Request URL (POST)

Header

Body

Success Response

Error response

d. Cancel subscription

Request URL (POST)

Header

Body

Success Response

Error responses

5. Error Handling