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
Subscription Creation -Create new subscriptions with predetermined billing frequencies
Subscription Cancellation - Terminate existing subscriptions when needed.
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:
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
Monitor Status (
GET
/v3/subscriptions/{id})Verify subscription activation
Check payment processing status
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:
Successful subscription creation (either via OneShot or PCI flow)
Proper payment verification using the deposits status endpoint
Proper subscription status verification
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.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.
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.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:
Payment Processing: The system processes a payment (initial or recurring)
Webhook Notification: A notification is sent to your configured URL with a
deposit_id
Deposit Status Endpoint: Query GET
v3/deposits/
{deposit_id}
to get payment details. You can find details of the endpoint here.Subscription Identification: The deposit response includes the related
subscription_id
Subscription Status Check: Query GET
v3/subscriptions/
{subscription_id}
to verify current status
Subscription Lifecycle
A typical subscription follows this lifecycle:
Creation: A subscription is created with customer, payment, and billing details
Activation: The initial payment is processed and the subscription becomes active
Recurring Billing: Payments are automatically processed according to the billing frequency
Updates: Subscription details may be modified (coming soon).
Cancellation: The subscription is terminated, stopping future payments.
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:
Review our Technical and Security Aspects documentation
Implement the Subscription Creation Endpoints
Choose your integration method: OneShot or PCI!
Set up status monitoring and notifications.
Implement the Deposit Status Endpoint and Subscription Status Endpoint.
Implement Subscription Cancellation functionality
Configure webhook handling for real-time notifications
Last updated
Was this helpful?