Skip to main content

​
Subscription API Documentation

​
Overview

The Subscription API provides endpoints for managing recurring payments and subscriptions between accounts in the wallet service.

​
Base URL

/api/v1/subscriptions

​
Authentication

All endpoints require authentication using an API key in the request headers:
  • X-API-KEY: Your API key

​
Endpoints

​
Create Subscription

Create a new subscription for recurring payments. Endpoint: POST /register Headers:
  • X-API-KEY (optional): API key for authentication
Request Body: 
{
  "debitAccountId": "string",
  "creditAccountId": "string",
  "amount": "number",
  "currency": "string",
  "frequency": "DAILY|WEEKLY|BI_WEEKLY|MONTHLY|YEARLY",
  "description": "string",
  "tenantId": "string",
  "userId": "string",
  "startTime": "string",
  "endTime": "string",
  "notificationUrl": "string"
}
Response: 
{
  "statusCode": 201,
  "message": "string",
  "data": {
    "subscriptionReference": "string",
    "debitAccount": {
      "accountId": "string",
      "accountNumber": "string",
      "accountName": "string",
      "currency": "string",
      "status": "string"
    },
    "creditAccount": {
      "accountId": "string",
      "accountNumber": "string",
      "accountName": "string",
      "currency": "string",
      "status": "string"
    },
    "amount": "number",
    "currency": "string",
    "frequency": "string",
    "status": "ACTIVE|PAUSED|COMPLETED|CANCELLED|FAILED|EXPIRED",
    "webhookUrl": "string",
    "startTime": "string",
    "nextDueTime": "string",
    "endTime": "string",
    "narration": "string",
    "count": "number"
  }
}

​
Update Subscription

Update an existing subscription. Endpoint: POST /update/{reference} Headers:
  • X-API-KEY (optional): API key for authentication
Path Parameters:
  • reference: Subscription reference ID
Request Body: 
{
  "debitAccountId": "string",
  "creditAccountId": "string",
  "amount": "number",
  "currency": "string",
  "frequency": "DAILY|WEEKLY|BI_WEEKLY|MONTHLY|YEARLY",
  "description": "string",
  "tenantId": "string",
  "userId": "string",
  "startTime": "string",
  "endTime": "string",
  "notificationUrl": "string"
}
Response: 
{
  "statusCode": 200,
  "message": "string",
  "data": {
    "subscriptionReference": "string",
    "debitAccount": {
      "accountId": "string",
      "accountNumber": "string",
      "accountName": "string",
      "currency": "string",
      "status": "string"
    },
    "creditAccount": {
      "accountId": "string",
      "accountNumber": "string",
      "accountName": "string",
      "currency": "string",
      "status": "string"
    },
    "amount": "number",
    "currency": "string",
    "frequency": "string",
    "status": "string",
    "webhookUrl": "string",
    "startTime": "string",
    "nextDueTime": "string",
    "endTime": "string",
    "narration": "string",
    "count": "number"
  }
}

​
Get Subscriptions

Retrieve subscriptions with filtering and pagination. Endpoint: GET / Headers:
  • X-API-KEY (optional): API key for authentication
Query Parameters:
  • debitAccountId: Filter by debit account ID
  • creditAccountId: Filter by credit account ID
  • status: Filter by subscription status
  • frequency: Filter by frequency
  • tenantId: Filter by tenant ID
  • startDateFrom: Filter by start date from
  • startDateTo: Filter by start date to
  • endDateFrom: Filter by end date from
  • endDateTo: Filter by end date to
  • currency: Filter by currency
  • page: Page number (default: 0)
  • size: Page size (default: 20)
  • sort: Sort field and direction (e.g., “createdAt,desc”)
Response: 
{
  "statusCode": 200,
  "message": "string",
  "data": {
    "content": [
      {
        "subscriptionReference": "string",
        "debitAccount": {
          "accountId": "string",
          "accountNumber": "string",
          "accountName": "string",
          "currency": "string",
          "status": "string"
        },
        "creditAccount": {
          "accountId": "string",
          "accountNumber": "string",
          "accountName": "string",
          "currency": "string",
          "status": "string"
        },
        "amount": "number",
        "currency": "string",
        "frequency": "string",
        "status": "string",
        "webhookUrl": "string",
        "startTime": "string",
        "nextDueTime": "string",
        "endTime": "string",
        "narration": "string",
        "count": "number"
      }
    ],
    "totalElements": "number",
    "totalPages": "number",
    "size": "number",
    "number": "number"
  }
}

​
Get Subscription Transactions

Retrieve transactions associated with a subscription. Endpoint: GET /transactions Headers:
  • X-API-KEY (optional): API key for authentication
Query Parameters:
  • status: Filter by transaction status
  • subscriptionReference: Filter by subscription reference
  • tenantId: Filter by tenant ID
  • type: Filter by transaction type
  • startDateFrom: Filter by start date from
  • startDateTo: Filter by start date to
  • endDateFrom: Filter by end date from
  • endDateTo: Filter by end date to
  • currency: Filter by currency
  • page: Page number (default: 0)
  • size: Page size (default: 20)
  • sort: Sort field and direction (e.g., “createdAt,desc”)
Response: 
{
  "statusCode": 200,
  "message": "string",
  "data": {
    "content": [
      {
        "transactionId": "string",
        "requestId": "string",
        "amount": "number",
        "currency": "string",
        "status": "string",
        "type": "string",
        "narration": "string",
        "createdAt": "string"
      }
    ],
    "totalElements": "number",
    "totalPages": "number",
    "size": "number",
    "number": "number"
  }
}

​
Error Responses

All endpoints may return the following error responses: 401 Unauthorized 
{
  "statusCode": 401,
  "message": "Unauthorized",
  "data": null
}
404 Not Found 
{
  "statusCode": 404,
  "message": "Resource not found",
  "data": null
}
409 Conflict 
{
  "statusCode": 409,
  "message": "Duplicate subscription",
  "data": null
}

​
Notes

  • All timestamps are in ISO-8601 format
  • Minimum subscription amount is 100 units of the specified currency
  • Subscription frequencies:
    • DAILY: Daily recurring payment
    • WEEKLY: Weekly recurring payment
    • BI_WEEKLY: Bi-weekly recurring payment
    • MONTHLY: Monthly recurring payment
    • YEARLY: Yearly recurring payment
  • Subscription statuses:
    • ACTIVE: Currently running
    • PAUSED: Temporarily halted
    • COMPLETED: Finished after reaching end time
    • CANCELLED: Manually cancelled
    • FAILED: Last execution failed
    • EXPIRED: Reached end time
  • Platform admins can create subscriptions for any tenant
  • Tenant admins can create subscriptions for their tenant
  • Regular users can only create subscriptions for themselves
  • Subscriptions are processed automatically based on their frequency
  • Failed subscriptions can be retried manually
  • Webhook notifications are sent for subscription events
  • Subscription history is maintained for audit purposes
  • Account currency must match the subscription currency
  • Subscriptions are unique per debit account, credit account, amount, currency, and frequency