Subscriptions API

The Subscriptions API enables merchants to create and manage recurring billing relationships with their customers.

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})

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

Subscription Cancellation Endpoint

This endpoint enables merchants to cancel active subscriptions.

DELETE https://api-stg.directa24.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.directa24.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.directa24.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. Implement the Subscription Creation Endpoints

    1. Choose your integration method: OneShot or PCI!

  2. Set up status monitoring and notifications.

  3. Implement Subscription Cancellation functionality

  4. Configure webhook handling for real-time notifications

Last updated

Was this helpful?