# Subscriptions API

## Overview

The Subscriptions API provides a complete solution for managing the entire subscription lifecycle, from initial creation to status monitoring and cancellation.\
The following operations are included in our API

1. **Subscription Creation** -Create new subscriptions with predetermined billing frequencies
2. **Subscription Cancellation** - Terminate existing subscriptions when needed.
3. **Subscription Status** - Retrieve detailed information about existing subscriptions

## Key Features

* **Multiple Integration Options**: Choose between OneShot Flow (redirect-based) or PCI Flow (direct card processing) based on your compliance status
* **Flexible Billing Frequencies**: Support for DAILY, WEEKLY, MONTHLY, and ANNUALLY billing cycles
* **Automatic Renewals**: Configure subscriptions to automatically renew or expire after a set period
* **Webhook Notifications**: Receive real-time updates about payment and subscription status changes
* **Comprehensive Reporting**: Access detailed information about subscription status and payment history

## Integration Flow

A typical integration with the Subscriptions API follows this sequence:

1. **Create Subscription** (<mark style="color:orange;">**`POST`**</mark> /v3/subscriptions)
   * Submit customer and billing information
   * For non-PCI flow: Redirect customer to payment page
   * For PCI flow: Submit payment details directly
2. **Monitor Status** (<mark style="color:green;">**`GET`**</mark> /v3/subscriptions/{id})
   * Verify subscription activation
   * Check payment processing status
3. **Manage Lifecycle** (as needed)
   * Cancel subscription (<mark style="color:red;">**`DELETE`**</mark> /v3/subscriptions/{id})
   * Check status changes (<mark style="color:green;">**`GET`**</mark> /v3/subscriptions/{id})

{% hint style="success" %}
**Integration Requirements**

To receive full integration approval and move to production, merchants must successfully implement **all core endpoints**. Our certification process requires demonstration of:

1. Successful [**subscription creation**](broken://pages/VNDXhgu3fIZthn1ebWG8) (either via OneShot or PCI flow)
2. Proper payment verification using the [**deposits status**](/api-documentation/deposits-api/endpoints/deposit-status-endpoint.md) endpoint
3. Proper [**subscription status**](broken://pages/nwkAnRTCuFMTdnDCxd05) verification
4. Correct [**subscription cancellation**](broken://pages/rmzQFp0CXZpC0CTH7Hou) handling

Only after all endpoints have been verified in the staging environment will merchants receive clearance to use the Subscriptions API in production. This ensures a complete integration that can properly manage the entire subscription lifecycle from creation to termination, including payment verification.
{% endhint %}

### Subscription Creation Endpoints

The API offers two distinct flows for creating subscriptions, catering to merchants with different PCI compliance levels:

#### &#x20;  OneShot Flow (Non-PCI)

For merchants without PCI certification, [this](broken://pages/oyb1RBbx84VBVE83WXha) flow allows subscription creation without handling sensitive payment data directly.

<mark style="color:orange;background-color:orange;">**POST**</mark> `https://api-stg.onekeypayments.com/v3/subscriptions`

The standard flow requires redirection to our secure payment page where customers can safely enter their payment details. All payment information is processed on our PCI-compliant servers.

#### &#x20;  PCI Flow

For PCI-certified merchants, [this](broken://pages/5WAIhpY6nhRwxkpRsoRJ) flow allows subscription creation with direct credit card submission.

<mark style="color:orange;background-color:orange;">**POST**</mark> `https://cc-api-stg.onekeypayments.com/v3/subscriptions`

The PCI flow enables merchants to collect and transmit credit card details directly within the API request, facilitating a seamless checkout experience without redirections.

{% hint style="success" %}
**Note:** To access the PCI flow, merchants must provide valid PCI AOC documentation and use the designated PCI endpoint.
{% endhint %}

### Subscription Cancellation Endpoint

[This](broken://pages/rmzQFp0CXZpC0CTH7Hou) endpoint enables merchants to cancel active subscriptions.

<mark style="color:red;background-color:red;">**DELETE**</mark> `https://api-stg.onekeypayments.com/v3/subscriptions/`**`{subscription_id}`**

When a subscription is cancelled:

* No further charges will be processed
* The subscription status will change to `CANCELLED`
* Existing transactions will remain unaffected.

### Deposit Status Endpoint

[This](/api-documentation/deposits-api/endpoints/deposit-status-endpoint.md) endpoint enables merchants to retrieve detailed information about a payment deposit associated with a subscription. **Note that those deposits will be generated automatically by the Subscription API.**

<mark style="color:green;background-color:green;">**GET**</mark> `https://api-stg.onekeypayments.com/v3/deposits/`**`{deposit_id}`**

The response includes comprehensive details about the deposit, including:

* Payment status
* Transaction amount
* Payment method used
* **Associated subscription ID**
* Processing date and time
* More information

### Subscription Status Endpoint

[This](broken://pages/nwkAnRTCuFMTdnDCxd05) endpoint enables merchants to retrieve detailed information about a subscription.

<mark style="color:green;background-color:green;">**GET**</mark> `https://api-stg.onekeypayments.com/v3/subscriptions/`**`{subscription_id}`**

The response includes comprehensive details about the subscription, including:

* Current status
* Payment history
* Upcoming billing dates
* Subscription terms

## Payment Notification Flow

When a payment event occurs for a subscription, our system notifies you through this process:

1. **Payment Processing**: The system processes a payment (initial or recurring)
2. **Webhook Notification**: A notification is sent to your configured URL with a `deposit_id`
3. **Deposit Status Endpoint**: Query <mark style="color:green;background-color:green;">**GET**</mark> `v3/deposits/`**`{deposit_id}`** to get payment details.\
   You can find details of the endpoint [here](/api-documentation/deposits-api/endpoints/deposit-status-endpoint.md).
4. **Subscription Identification**: The deposit response includes the related `subscription_id`
5. **Subscription Status Check**: Query <mark style="color:green;background-color:green;">**GET**</mark> `v3/subscriptions/`**`{subscription_id}`** to verify current status

## Subscription Lifecycle

A typical subscription follows this lifecycle:

1. **Creation**: A subscription is created with customer, payment, and billing details
2. **Activation**: The initial payment is processed and the subscription becomes active
3. **Recurring Billing**: Payments are automatically processed according to the billing frequency
4. **Updates**: Subscription details may be modified (*coming soon*).
5. **Cancellation**: The subscription is terminated, stopping future payments.
6. **Completion**: The subscription reaches its natural end date (if not set to auto-renew)

## Authentication Requirements

All Subscriptions API endpoints require the following [authentication](broken://pages/vFdXgiAjIGSHF4sv2ch5#headers) headers:

* **X-Login**: Your merchant API key
* **X-Date**: Current timestamp in ISO 8601 format
* **Authorization**: Authentication hash
* **Content-Type**: application/json

## Response Codes

The API uses standard HTTP response codes and includes detailed information in the response body:

* **2xx**: Success
* **4xx**: Client errors (invalid input, authentication issues)
* **5xx**: Server errors

Each error response includes a code, description, and type field to help with troubleshooting.

***

## Getting Started

To begin integrating with the Subscriptions API:

1. Review our [Technical and Security Aspects documentation](broken://pages/vFdXgiAjIGSHF4sv2ch5)
2. Implement the [Subscription Creation Endpoints](broken://pages/VNDXhgu3fIZthn1ebWG8)
   1. Choose your integration method: OneShot or PCI!
3. Set up status monitoring and notifications.
4. Implement the [Deposit Status Endpoint](/api-documentation/deposits-api/endpoints/deposit-status-endpoint.md) and [Subscription Status Endpoint](broken://pages/nwkAnRTCuFMTdnDCxd05).
5. Implement [Subscription Cancellation](broken://pages/rmzQFp0CXZpC0CTH7Hou) functionality
6. Configure webhook handling for real-time notifications


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://apidocs.onekeypayments.com/api-documentation/subscriptions-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.