Skip to main content

​
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: 
{
  "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: 
{
  "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: 
{
  "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 
{
  "statusCode": 401,
  "message": "Unauthorized",
  "data": null
}
404 Not Found 
{
  "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