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

Getting Started

Core Features

Additional Features

Subscription API

Subscription API Documentation

Overview

Base URL

Authentication

Endpoints

Create Subscription

Update Subscription

Get Subscriptions

Get Subscription Transactions

Error Responses

Notes

​Subscription API Documentation

​Overview

​Base URL

​Authentication

​Endpoints

​Create Subscription

​Update Subscription

​Get Subscriptions

​Get Subscription Transactions

​Error Responses

​Notes

Subscription API Documentation

Overview

Base URL

Authentication

Endpoints

Create Subscription

Update Subscription

Get Subscriptions

Get Subscription Transactions

Error Responses

Notes