> ## Documentation Index
> Fetch the complete documentation index at: https://dvaultdocs.dukka.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Charge API

> Manage transaction charges and fees

# 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:**

```json theme={null}
{
  "paymentMethod": "string",
  "transactionType": "string",
  "tenantCharge": "string",
  "platformCharge": "string",
  "currency": "string",
  "cardType": "string"
}
```

**Response:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "paymentMethod": "string",
  "transactionType": "string",
  "tenantCharge": "string",
  "platformCharge": "string",
  "currency": "string",
  "cardType": "string"
}
```

**Response:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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**

```json theme={null}
{
  "statusCode": 401,
  "message": "not permitted to configure charge",
  "data": null
}
```

**404 Not Found**

```json theme={null}
{
  "statusCode": 404,
  "message": "Charge not found",
  "data": null
}
```

**409 Conflict**

```json theme={null}
{
  "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