# 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**](https://apidocs.onekeypayments.com/api-documentation/broken-reference) (either via OneShot or PCI flow)
2. Proper payment verification using the [**deposits status**](https://apidocs.onekeypayments.com/api-documentation/deposits-api/endpoints/deposit-status-endpoint) endpoint
3. Proper [**subscription status**](https://apidocs.onekeypayments.com/api-documentation/broken-reference) verification
4. Correct [**subscription cancellation**](https://apidocs.onekeypayments.com/api-documentation/broken-reference) 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](https://apidocs.onekeypayments.com/api-documentation/broken-reference) 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](https://apidocs.onekeypayments.com/api-documentation/broken-reference) 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](https://apidocs.onekeypayments.com/api-documentation/broken-reference) 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](https://apidocs.onekeypayments.com/api-documentation/deposits-api/endpoints/deposit-status-endpoint) 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](https://apidocs.onekeypayments.com/api-documentation/broken-reference) 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](https://apidocs.onekeypayments.com/api-documentation/deposits-api/endpoints/deposit-status-endpoint).
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](https://apidocs.onekeypayments.com/api-documentation/broken-reference) 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](https://apidocs.onekeypayments.com/api-documentation/broken-reference)
2. Implement the [Subscription Creation Endpoints](https://apidocs.onekeypayments.com/api-documentation/broken-reference)
   1. Choose your integration method: OneShot or PCI!
3. Set up status monitoring and notifications.
4. Implement the [Deposit Status Endpoint](https://apidocs.onekeypayments.com/api-documentation/deposits-api/endpoints/deposit-status-endpoint) and [Subscription Status Endpoint](https://apidocs.onekeypayments.com/api-documentation/broken-reference).
5. Implement [Subscription Cancellation](https://apidocs.onekeypayments.com/api-documentation/broken-reference) functionality
6. Configure webhook handling for real-time notifications