Developer Center

Subscription Method

When your customer chooses this method, the periodic products/services in the cart will be enabled for the automatic renewal feature.

The "Subscription" method works the same as the "Third Party" and "Merchant" methods. In addition, a subscription ID is defined for each item in the cart.

Assigning a Subscription ID

You can use the sample code below in "capture", "area" , "callback" functions. The subscription ID will appear on the “Admin Area > Product/Service Detail” page.

if($items = $this->subscribable_items())
{
    $subscribed = [];
    foreach($items AS $item)
        $subscribed[$item['identifier']] = 'Here Subscription ID';
    if($subscribed) $this->set_subscribed_items($subscribed);
}

The return value from the "subscribable_items" function is an array loop. The parameters are explained below:

Name Type Explanation
identifier string Required to identify the "Subscription ID"
product_type string Type of product (can be: 'hosting', 'server' , 'domain', 'software', 'special', 'sms')
product_id integer Product ID number
period string Type of selected period (can be 'hour','day','week','month','year')
period_time integer Time of the selected period
name string Product name
amount float The tax-free fee of the product
tax_included float The price of the product including tax
tax_exempt integer "1" if the product is tax exempt, otherwise "0"
tax_rate integer Tax rate
currency integer Currency. You can convert it to currency code using the "$this->currency()" function.

A subscription ID is defined for services purchased with the "set_subscribed_items" function. The parameter to be sent must be an array. Define the "identifier" value you get in the array loop returning the key value of the array from the "subscribable_items" function. Then define the "subscriber ID number" obtained from the payment service provider to the value of the directory.

Variables

The following parameters are used in the "get_subscription" , "cancel_subscription" , "change_subscription_fee" , "capture_subscription" functions.

Name Type Explanation
id integer Subscriber ID is the database ID number
user_id integer Customer's ID number
items array Information from the "subscribable_items" function
status string Subscription status, possible values: (approved, active, suspended, canceled, expired)
status_msg string An explanation of the status of the subscription, if any
identifier string Identification number of the subscription
currency integer Currency. You can convert it to currency code using the "$this->currency()" function.
first_paid_fee float First paid fee
last_paid_fee float Last paid fee
next_payable_fee float Next payable fee
last_paid_date string The date of the last payment. format: YYYY-MM-DD HH:ii:ss
next_payable_date string Next payable date. format: YYYY-MM-DD HH:ii:ss
created_at String First paid date. format: YYYY-MM-DD HH:ii:ss

Subscription Status

The "get_subscription" function is used to get up-to-date information about the subscription status, date and amount paid. If a service has a subscription ID defined, the use of the function is mandatory.

Sample
public function get_subscription($params=[])
{
    $sub_id             = $params["identifier"];

    /*
     * From here, you can send an API command to the payment service provider and report the status of the subscription according to the response you receive.
     */

    return [
        'status'            => 'active',
        'status_msg'        => '',
        'first_paid'        => [
            'time'              => '2021-07-01 13:00:00',
            'fee'               => [
                'amount'    => 15,
                'currency'  => 'USD',
            ],
        ],
        'last_paid'         => [
            'time'          => '2021-08-01 13:00:00',
            'fee'           => [
                'amount'    => 15,
                'currency'  => 'USD',
            ],
        ],
        'next_payable'      => [
            'time'              => '2021-09-01 13:00:00',
            'fee'               => [
                'amount'            => 15,
                'currency'          => 'USD',
            ],
        ],
        'failed_payments'   => 0,
    ];

}
Response

Here are the parameters that should be returned from the "get_subscription" function:

Name Type Explanation
status string Subscription status, possible values: (approved, active, suspended, canceled, expired)
status_msg string An explanation of the status of the subscription, if any
first_paid array Subscription start date and price
first_paid -> time string First paid date. format: YYYY-MM-DD HH:ii:ss
first_paid -> fee float First paid fee
last_paid array The last payment date and amount of the subscription
last_paid -> time string The date of the last payment. format: YYYY-MM-DD HH:ii:ss
last_paid -> fee float Last paid fee
next_payable array Next payment date and fee
next_payable -> time string Next due date, format: YYYY-MM-DD HH:ii:ss
next_payable -> fee float The next fee payable
Failed_payments integer Number of failed payments

Collecting Instant Payment

If your payment service provider supports instant payment collection, you can use the "capture_subscription" function for overdue subscriptions and collect the payment immediately.

Sample

The parameters sent to the function are explained in the "Variables" section above.

public function capture_subscription($params=[])
{
    $sub_id     = $params["identifier"];
    $amount     = $params["next_payable_fee"];
    $curr       = $params["currency"];

    $request_fields        = [
        'note'          => 'pay the remaining balance',
        'currency'      => $this->currency($curr),
        'amount'        => $amount,
    ];

    $request            = "failed";

    if($request == "failed")
    {
        $this->error = 'Payment cannot be captured.';
        return false;
    }

    return true;
}
Response

The response that should be returned must be a "boolean".

Subscription Fee Update

If your payment service provider supports updating the subscription fee, you can use the "change_subscription_fee" function.

Due to price changes applied to the products and changes in the exchange rate, the price information of the subscription can be updated with this function.

The function is run for each "item" in the subscription.

Sample

$params > Variable content is described in the "Variables" heading. (array)
$value > Amount information (float)
$currency > Currency ID (int)

public function change_subscription_fee($params=[],$value = 0,$currency=0)
{
    $sub_id     = $params["identifier"];

    $request_fields    = [
        'sub_id'        => $sub_id,
        'amount'        => $value,
        'currency'      => $this->currency($currency),
    ];

    $request            = 'failed';

    if($request == 'failed')
    {
        $this->error = 'The subscription fee cannot change.';
        return false;
    }

    return true;
}
Response

The response that should be returned must be a "boolean".

Subscription Cancellation

In case of cancellation of subscription, "cancel subscription" function is triggered.

Sample

The parameters sent to the function are explained in the "Variables" section above.

public function cancel_subscription($params=[])
{
    $sub_id = $params["identifier"];

    /*
     * From here you can send an API command to the payment service provider and, based on the response you receive, report the subscription cancellation.
     */
    $request = 'CRITICAL ERROR';

    if($request == 'CRITICAL ERROR')
    {
        $this->error = 'Subscription cannot be cancelled.';
        return false;
    }
    return true;
}
Response

The response that should be returned must be a "boolean".

Tokenized Method Card No Verification (BIN Check)

Do you have any questions?

Feel free to contact us
Contact Us
Copyright © 2024. All Rights Reserved.
Join Our Discord Channel
Top