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 (POST /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 (GET /v3/subscriptions/{id})

    • Verify subscription activation

    • Check payment processing status

  3. Manage Lifecycle (as needed)

    • Cancel subscription (DELETE /v3/subscriptions/{id})

    • Check status changes (GET /v3/subscriptions/{id})

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 (either via OneShot or PCI flow)

  2. Proper payment verification using the deposits status endpoint

  3. Proper subscription status verification

  4. Correct subscription cancellation 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.

Subscription Creation Endpoints

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

OneShot Flow (Non-PCI)

For merchants without PCI certification, this flow allows subscription creation without handling sensitive payment data directly.

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

PCI Flow

For PCI-certified merchants, this flow allows subscription creation with direct credit card submission.

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

Note: To access the PCI flow, merchants must provide valid PCI AOC documentation and use the designated PCI endpoint.

Subscription Cancellation Endpoint

This endpoint enables merchants to cancel active subscriptions.

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

GET 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 endpoint enables merchants to retrieve detailed information about a subscription.

GET 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 GET v3/deposits/{deposit_id} to get payment details. You can find details of the endpoint here.

  4. Subscription Identification: The deposit response includes the related subscription_id

  5. Subscription Status Check: Query GET 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 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

  2. Implement the Subscription Creation Endpoints

    1. Choose your integration method: OneShot or PCI!

  3. Set up status monitoring and notifications.

  4. Implement the Deposit Status Endpoint and Subscription Status Endpoint.

  5. Implement Subscription Cancellation functionality

  6. Configure webhook handling for real-time notifications

PreviousAPI CodesNextTechnical and Security Aspects

Last updated