# Subscriptions

Glomo Subscriptions enable merchants to automate recurring billing, providing a seamless experience for both businesses and customers. Businesses can create and manage subscriptions directly from the Glomopay dashboard. Once a subscription is made, Glomopay handles customer billing, payment notices, status tracking, and updates to subscription state.

## Key Features:

- **Automated Billing:** Once a subscription is set up, Glomopay automatically handles recurring charges, reducing manual intervention and ensuring timely payments.
- **Seamless Pre-Authorization:** Customers can pre-authorize their subscription, confirming their payment method in advance so the first scheduled charge happens smoothly.
- **Flexible Billing Models:** Support for various billing frequencies and amounts, accommodating diverse business needs.
- **Customer-Friendly Checkout:** A streamlined checkout process that allows customers to easily subscribe and manage their payment methods.
- **Comprehensive Subscription Management:** Tools to pause, resume, or cancel subscriptions, providing full control over the subscription lifecycle.
- **Real-Time Notifications:** Instant alerts on payment activities and subscription status changes, keeping you informed at every step.


## Steps to Create a Subscription

You can create a subscription directly from the Glomopay dashboard. Here’s how:

| State | Description |
|  --- | --- |
|  Created  | Subscription is created by the merchant. No payment has been made yet. |
|  Authorized  | The user has successfully set up the subscription. Recurring payments will start on the scheduled date. |
|  Active  | Subscription is active after the first successful payment, or resumed after a pause. Recurring billing continues. |
|  Paused  | Subscription is paused by the merchant. No further payments will be charged 
until resumed. |
|  Completed  | The subscription has run its full billing cycle and is now complete. |
|  Expired  | The customer didn’t complete payment before the link expired. The subscription is no longer valid. |
|  Halted  | A scheduled payment failed (after retries). Subscription is paused pending manual reactivation. |
|  Cancelled  | Subscription is cancelled by the merchant. No further billing will occur. |


## Steps to integrate the Subscription on checkout

## Step 1 : Create a Subscription in the Server

Use your server and Glomopay secret keys to create a subscription via the Create Subscription API.

### API Endpoint


```curl
POST https://api.glomopay.com/api/v1/subscriptions
```

### Request


```http
curl -i -X POST \
  https://api.glomopay.com/api/v1/subscriptions \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "customer_id": "cust_5JU9yv0lGSUP",
    "product_name": "ShieldGuard Insurance",
    "product_description": "Flexible, monthly insurance for belongings, travel, and digital assets; easy to manage",
    "plan_name": "ShieldGuard Lite",
    "plan_description": "Simple, monthly insurance plan that covers your basic belongings and key digital assets",
    "amount": 1000,
    "currency": "USD",
    "interval_type": "month",
    "interval_count": 1,
    "billing_cycles": 12,
    "start_date": "2025-01-01",
    "expires_at": "2025-01-07",
    "notify_customer": true,
    "starts_with_first_payment": true
  }'
```

### Response


```http
{
  "id": "sub_5JU9yv0lGSUP",
  "customer_id": "cust_5JU9yv0lGSUP",
  "product_name": "ShieldGuard Insurance",
  "product_description": "Flexible, monthly insurance for belongings, travel, and digital assets; easy to manage",
  "plan_name": "ShieldGuard Lite",
  "plan_description": "Simple, monthly insurance plan that covers your basic belongings and key digital assets",
  "status": "active",
  "amount": 1000,
  "currency": "USD",
  "interval_type": "month",
  "interval_count": 1,
  "billing_cycles": 12,
  "start_date": "2025-01-01",
  "end_date": "2025-12-01",
  "expires_at": "2025-01-07",
  "next_payment_date": "2025-02-01",
  "subscription_link_url": "https://checkout.glomopay.com/subscription/sub_5JU9yv0lGSUP",
  "cancelled_at": "2025-01-15"
}
```

You will receive an “**id**” in the response. This **id** should be passed to the Checkout SDK.

## Step 2 : Add a Subscribe Button on checkout

Add a "**Subscribe**" button to your website and integrate the Glomo Checkout SDK as shown below:


```html
<button id="buy-button" class="buy-button">Buy Now</button>
  <script type="module">
    import { GlomoCheckoutApi } from 'https://glomopay-checkout-sdk.web.app/index.js';

    const checkout = new GlomoCheckoutApi({
      SubscriptionId: 'sub_679a16457aP6K', // Pass the order_id received from the server in step 1
      publicKey: 'live_687b0151Bid24PAI', // Pass the public key received from the dashboard
      callbackUrl: 'https://yourwebsite.com/payment-result', // Optional: URL to redirect after payment completion
    });

    document.getElementById('buy-button').addEventListener('click', () => {
      checkout.open();
    });

    checkout.on('payment.success', function (response) {
      // Handle payment success
    });

  checkout.on('payment.failure', function (response) {
      // Handle payment failure
    });
  </script>
```

### Notes:

- The code snippet will create a **checkout instance** and open the **checkout form** when the user clicks on the subscribe button.
- The **subscription** created via your server in **Step 1** should be passed to the checkout instance.
- Handle the payment success and failure events, in the handlers function you will get **payment object** or **error object** based on the payment status. Collect these and send them to your server and retry accordingly in case payment fails.
- If a **callbackUrl** is provided, users will be redirected to that URL after payment completion. In this case, the **success** and **failure** event handlers will not be triggered.


### About the Callback URL

When you provide a callbackUrl, the user will be automatically redirected to that URL after payment completion with the following parameters:

### For successful payments:


```curl
https://yourwebsite.com/payment-result?status=success&orderId=123456&signature=abc123def456
```

### For failed payments:


```curl
https://yourwebsite.com/payment-result?status=failed&orderId=123456&signature=abc123def456
```

This allows server-side handling of payment results in addition to the client-side event handlers.

## Step 3: Verify checkout response and signature on the server

In the payment response, you will receive a **payment_id**, **subscription_id**, **status**, and a **signature**. You must validate the signature using your Glomo secret key to confirm payment authenticity.

### Sample code to verify the signature


```php
<?php
function generate_signature($order_id, $payment_id, $status, $secret) {
    $data = $order_id . "|" . $payment_id . "|" . $status;
    return hash_hmac('sha256', $data, $secret);
}

// Example Usage
$subscription_id = "sub_679a16457aP6K";
$payment_id = "payment_679a16457an6K";
$status = "success";
$secret = "your_secret_key";

echo generate_signature($order_id, $payment_id, $status, $secret);
?>
```

## Step 4: Verify payment status

Payment's status can be tracked in the following ways

- You can track the payments linked to your **sub_id** via **dashboard**.
- You can also track the payment status via polling the **[Payment APIs](https://docs.glomopay.com/api-documentation/apis/openapi/payment/getpaymentbyid)**.
- You can also track the payment status via **[Webhooks](https://docs.glomopay.com/api-documentation/webhooks)** which will notify you about the payment status.