Skip to main content

​
Charge API Documentation

​
Overview

The Charge API provides endpoints for managing transaction charges and fees in the wallet service. It supports configuring charges for different payment methods, transaction types, and currencies.

​
Base URL

/api/v1/charges

​
Authentication

All endpoints require authentication using an API key in the request headers:
  • X-API-KEY: Your API key
  • X-Tenant-ID: Tenant identifier (required for platform admins)

​
Endpoints

​
Create Charge

Create a new charge configuration. Endpoint: POST /create Headers:
  • X-API-KEY: API key for authentication
  • X-Tenant-ID: Tenant identifier (required for platform admins)
Request Body: 
{
  "paymentMethod": "string",
  "transactionType": "string",
  "tenantCharge": "string",
  "platformCharge": "string",
  "currency": "string",
  "cardType": "string"
}
Response: 
{
  "statusCode": 201,
  "message": "string",
  "data": {
    "id": "number",
    "paymentMethod": "string",
    "transactionType": "string",
    "tenantCharge": "string",
    "platformCharge": "string",
    "tenantId": "string",
    "currency": "string",
    "cardType": "string",
    "createdAt": "string",
    "updatedAt": "string"
  }
}

​
Update Charge

Update an existing charge configuration. Endpoint: PUT /update/{Id} Headers:
  • X-API-KEY: API key for authentication
  • X-Tenant-ID: Tenant identifier (required for platform admins)
Path Parameters:
  • Id: The ID of the charge configuration to update
Request Body: 
{
  "paymentMethod": "string",
  "transactionType": "string",
  "tenantCharge": "string",
  "platformCharge": "string",
  "currency": "string",
  "cardType": "string"
}
Response: 
{
  "statusCode": 200,
  "message": "string",
  "data": {
    "id": "number",
    "paymentMethod": "string",
    "transactionType": "string",
    "tenantCharge": "string",
    "platformCharge": "string",
    "tenantId": "string",
    "currency": "string",
    "cardType": "string",
    "createdAt": "string",
    "updatedAt": "string"
  }
}

​
View Charges

Retrieve charge configurations with filtering and pagination. Endpoint: GET /get Headers:
  • X-API-KEY: API key for authentication
  • X-Tenant-ID: Tenant identifier (required for platform admins)
Query Parameters:
  • paymentMethod: Filter by payment method
  • transactionType: Filter by transaction type
  • tenantCharge: Filter by tenant charge formula
  • platformCharge: Filter by platform charge formula
  • tenantId: Filter by tenant ID
  • 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": [
      {
        "id": "number",
        "paymentMethod": "string",
        "transactionType": "string",
        "tenantCharge": "string",
        "platformCharge": "string",
        "tenantId": "string",
        "currency": "string",
        "cardType": "string",
        "createdAt": "string",
        "updatedAt": "string"
      }
    ],
    "pageable": {
      "pageNumber": "number",
      "pageSize": "number",
      "sort": {
        "sorted": "boolean",
        "unsorted": "boolean",
        "empty": "boolean"
      },
      "offset": "number",
      "paged": "boolean",
      "unpaged": "boolean"
    },
    "totalElements": "number",
    "totalPages": "number",
    "last": "boolean",
    "size": "number",
    "number": "number",
    "sort": {
      "sorted": "boolean",
      "unsorted": "boolean",
      "empty": "boolean"
    },
    "numberOfElements": "number",
    "first": "boolean",
    "empty": "boolean"
  }
}

​
Error Responses

401 Unauthorized 
{
  "statusCode": 401,
  "message": "not permitted to configure charge",
  "data": null
}
404 Not Found 
{
  "statusCode": 404,
  "message": "Charge not found",
  "data": null
}
409 Conflict 
{
  "statusCode": 409,
  "message": "charge already exist",
  "data": null
}

​
Notes

  • Charge Configuration:
    • Supports multiple payment methods
    • Supports different transaction types
    • Supports various currencies
    • Supports card type-specific charges
  • Charge Formulas:
    • Percentage-based charges (e.g., “1.5”)
    • Flat charges (e.g., “FLAT=100”)
    • Capped charges (e.g., “1.5|CAP=1000”)
    • Minimum charges (e.g., “1.5|FLOOR=50”)
    • Combined formulas (e.g., “1.5|CAP=1000|FLOOR=50”)
  • Charge Processing:
    • Tenant charges are processed first
    • Platform charges are processed after tenant charges
    • Charges are processed asynchronously
    • Failed charges are retried
  • Charge Validation:
    • Duplicate charges are prevented
    • Charge formulas are validated
    • Currency compatibility is checked
    • Payment method support is verified
  • Charge Permissions:
    • Tenant admins can manage their charges
    • Platform admins can manage all charges
    • Regular users cannot manage charges
  • Charge Tracking:
    • All charges are logged
    • Charge history is maintained
    • Charge status is tracked
    • Failed charges are monitored
  • Charge Notifications:
    • Charge transactions are notified
    • Failed charges are reported
    • Charge updates are logged
  • Charge Settlement:
    • Charges are settled immediately
    • Settlement status is tracked
    • Failed settlements are handled
    • Settlement notifications are sent