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 a Business App

  1. Sign in to your PayHere account & go to Settings > Business Apps section
  2. Click 'Create App' button & enter an app name & comma seperated domains to whilelist
  3. Tick the permission 'Subscription Management API'
  4. Click 'Add Business App' button to create the app
  5. Once the app is created click 'View Credential' button in front of the created app
  6. Copy the 'App ID' & 'App Secret' values


2. Generate an Authorization code

  1. Go to a Base64 encoding site such as https://www.base64encode.net/
  2. Paste the App ID & App Secret you copied from Step 1 above, separated by a colon (:) mark. eg. 4OVx33RVOPg4DzdZUzq4A94D2:8n4VCj25MXp4JLDFyvsE9h4a8qgbPaZUI4JEWK4FCvop
  3. 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. API calls

Consume the Subscription API with a valid access_token to load all the subscriptions programmatically on demand.

(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)

All Subscriptions

Request URL (GET)
Sandbox - https://sandbox.payhere.lk/merchant/v1/subscription
Live    - https://www.payhere.lk/merchant/v1/subscription
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": "saman@gmail.com",
                "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

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

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": "saman@gmail.com",
                "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": "saman@gmail.com",
                "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
                }
            ]
        }
    ]
}



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

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


Please note that;

  • 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 9th May 2019