> ## 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.

# Transaction API

> Process and manage financial transactions

# Transaction API Documentation

## Overview

The Transaction API provides endpoints for managing and retrieving transaction records in the wallet service, including transaction history, details, and reversal operations.

## Base URL

`/api/v1/transactions`

## 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 most endpoints)

## Endpoints

### Get Transactions

Retrieve transactions with filtering and pagination.

**Endpoint:** `GET /`

**Headers:**

* `X-API-KEY` (optional): API key for authentication
* `X-Tenant-ID` (optional): Tenant identifier

**Query Parameters:**

* `transactionId`: Filter by transaction ID (comma-separated for multiple IDs)
* `tenantId`: Filter by tenant ID (comma-separated for multiple IDs)
* `reference`: Filter by transaction reference (comma-separated for multiple references)
* `status`: Filter by transaction status (PENDING, APPROVED, REJECTED, REVERSED, PROCESSING, FAILED, ABANDONED, PROCESSED, SETTLEMENT\_PENDING\_WALLET\_DEBIT)
* `type`: Filter by transaction type (DEBIT, CREDIT)
* `paymentMethod`: Filter by payment method (INTRA\_WALLET, CARD, USSD, etc.)
* `currency`: Filter by currency (comma-separated for multiple currencies)
* `beneficiaryEmail`: Filter by beneficiary email (comma-separated for multiple emails)
* `beneficiaryPhone`: Filter by beneficiary phone number
* `accountId`: Filter by account ID
* `requestId`: Filter by request ID (comma-separated for multiple IDs)
* `providerReference`: Filter by provider reference (comma-separated for multiple references)
* `userId`: Filter by user 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": [
      {
        "transactionId": "string",
        "tenantId": "string",
        "amount": "number",
        "fee": "number",
        "type": "string",
        "reference": "string",
        "status": "string",
        "paymentMethod": "string",
        "narration": "string",
        "notified": "boolean",
        "requestId": "string",
        "currency": "string",
        "accountId": "string",
        "feeFormula": "string",
        "authUrl": "string",
        "authCode": "string",
        "providerReference": "string",
        "beneficiaryName": "string",
        "beneficiaryEmail": "string",
        "beneficiaryPhone": "string",
        "reason": "string",
        "userId": "string",
        "pan": "string",
        "eodDate": "string",
        "eodReference": "string",
        "createdAt": "string",
        "updatedAt": "string"
      }
    ],
    "totalElements": "number",
    "totalPages": "number",
    "size": "number",
    "number": "number"
  }
}
```

### Get Single Transaction

Retrieve details of a specific transaction.

**Endpoint:** `GET /{transactionReference}`

**Headers:**

* `X-API-KEY`: API key for authentication
* `X-Tenant-ID` (optional): Tenant identifier

**Path Parameters:**

* `transactionReference`: The reference of the transaction to retrieve

**Response:**

```json theme={null}
{
  "statusCode": 200,
  "message": "string",
  "data": {
    "transactionId": "string",
    "tenantId": "string",
    "amount": "number",
    "fee": "number",
    "type": "string",
    "reference": "string",
    "status": "string",
    "paymentMethod": "string",
    "narration": "string",
    "notified": "boolean",
    "requestId": "string",
    "currency": "string",
    "accountId": "string",
    "feeFormula": "string",
    "authUrl": "string",
    "authCode": "string",
    "providerReference": "string",
    "beneficiaryName": "string",
    "beneficiaryEmail": "string",
    "beneficiaryPhone": "string",
    "reason": "string",
    "userId": "string",
    "pan": "string",
    "eodDate": "string",
    "eodReference": "string",
    "createdAt": "string",
    "updatedAt": "string"
  }
}
```

### Reverse Transaction

Reverse a specific transaction.

**Endpoint:** `GET /reverse/{transactionReference}`

**Headers:**

* `X-API-KEY`: API key for authentication
* `X-Tenant-ID` (optional): Tenant identifier

**Path Parameters:**

* `transactionReference`: The reference of the transaction to reverse

**Response:**

```json theme={null}
{
  "statusCode": 200,
  "message": "string",
  "data": {
    "transactionId": "string",
    "tenantId": "string",
    "amount": "number",
    "fee": "number",
    "type": "string",
    "reference": "string",
    "status": "string",
    "paymentMethod": "string",
    "narration": "string",
    "notified": "boolean",
    "requestId": "string",
    "currency": "string",
    "accountId": "string",
    "feeFormula": "string",
    "authUrl": "string",
    "authCode": "string",
    "providerReference": "string",
    "beneficiaryName": "string",
    "beneficiaryEmail": "string",
    "beneficiaryPhone": "string",
    "reason": "string",
    "userId": "string",
    "pan": "string",
    "eodDate": "string",
    "eodReference": "string",
    "createdAt": "string",
    "updatedAt": "string"
  }
}
```

## Error Responses

All endpoints may return the following error responses:

**401 Unauthorized**

```json theme={null}
{
  "statusCode": 401,
  "message": "Unauthorized",
  "data": null
}
```

**404 Not Found**

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

## Notes

* All timestamps are in ISO-8601 format
* Transaction types:
  * DEBIT: Money leaving the account
  * CREDIT: Money entering the account
* Transaction statuses:
  * PENDING: Transaction is awaiting processing
  * APPROVED: Transaction has been successfully processed
  * REJECTED: Transaction was rejected
  * REVERSED: Transaction was reversed
  * PROCESSING: Transaction is being processed
  * FAILED: Transaction failed
  * ABANDONED: Transaction was abandoned
  * PROCESSED: Transaction has been processed
  * SETTLEMENT\_PENDING\_WALLET\_DEBIT: Settlement is pending wallet debit
* Payment methods include:
  * INTRA\_WALLET: Transfer between accounts in the same wallet
  * CARD: Card payment
  * USSD: USSD payment
  * And other payment methods
* Transaction access:
  * Platform admins can view all transactions
  * Tenant admins can view transactions for their tenant
  * Regular users can only view their own transactions
* Transaction reversal:
  * Only approved transactions can be reversed
  * Reversal creates a new transaction with opposite type
  * Original transaction status is updated to REVERSED
* Transaction notifications:
  * Users are notified of transaction status changes
  * Notifications can be configured per tenant
* Transaction limits:
  * Transactions are subject to tier limits
  * Limits are enforced at the account level
* Transaction history:
  * All transactions are permanently recorded
  * Transaction history is maintained for audit purposes
* Transaction fees:
  * Fees are calculated based on fee formula
  * Fees are included in the transaction amount
* Transaction security:
  * All transactions require authentication
  * Sensitive data is encrypted
  * Transaction logs are maintained for security