Skip to main content

​
Transaction Management Schemas

API endpoints for monitoring and tracking payment transactions.

​
Endpoints

MethodEndpointDescription
GET/v1/transaction-historyGet transaction history with filters
GET/v1/transaction-detailsGet detailed transaction information

​
GET /v1/transaction-history

Retrieve transaction history with extensive filtering and pagination options.

​
Query Parameters

ParameterTypeRequiredDescription
pagenumberNoPage number for pagination
limitnumberNoNumber of results per page
searchstringNoSearch by name, tracking ID, or fee ID
statusstringNoFilter by transaction status
minAmountnumberNoMinimum transaction amount
maxAmountnumberNoMaximum transaction amount
startDatestringNoStart date for date range filter
endDatestringNoEnd date for date range filter
settlementStatusstringNoFilter by settlement status
customerIdstringNoFilter by customer ID
feeIdstringNoFilter by fee ID
sortBystringNoField to sort by
sortOrderstringNoSort order (asc or desc)

​
Response Schema

{
  "statusCode": 200,
  "success": true,
  "data": {
    "items": [
      {
        "internalTrackingId": "string",
        "type": "payment",
        "amount": 7500,
        "status": "completed",
        "currency": "NGN",
        "narration": "string",
        "settlement": {
          "settlementType": "EOD",
          "dueDate": "string",
          "settlementMethod": "automated_clearing",
          "isSettled": false
        },
        "customerId": "string",
        "entityId": "string",
        "bankId": "string",
        "fees": {
          "id": "string",
          "amount": 150,
          "type": "processing_fee"
        },
        "parties": {
          "source": {
            "name": "string",
            "accountType": "customer",
            "direction": "outflow"
          },
          "destination": {
            "name": "string",
            "accountType": "merchant",
            "direction": "inflow"
          }
        },
        "createdAt": "string",
        "updatedAt": "string"
      }
    ],
    "total": 1,
    "page": 1
  }
}

​
GET /v1/transaction-details

Get detailed information about a specific transaction.

​
Query Parameters

ParameterTypeRequiredDescription
transactionIdstringNoTransaction ID (one of transactionId or internalTrackingId required)
internalTrackingIdstringNoInternal tracking ID

​
Response Schema

{
  "statusCode": 200,
  "success": true,
  "data": {
    "internalTrackingId": "string",
    "type": "payment",
    "amount": 7500,
    "status": "completed",
    "authType": "string",
    "service": {
      "id": "string",
      "name": "string"
    },
    "currency": "NGN",
    "narration": "string",
    "settlement": {
      "settlementType": "EOD",
      "dueDate": "string",
      "settlementMethod": "automated_clearing",
      "isSettled": false
    },
    "entityId": "string",
    "bankId": "string",
    "fees": {
      "id": "string",
      "entityId": "string",
      "bankId": "string",
      "amount": 150,
      "baseAmount": 7500,
      "currency": "NGN",
      "type": "processing_fee",
      "feeConfiguration": {
        "percentage": 2,
        "flat": 50,
        "cap": 200
      }
    },
    "parties": {
      "source": {
        "name": "string",
        "accountType": "customer",
        "direction": "outflow"
      },
      "destination": {
        "name": "string",
        "accountType": "merchant",
        "direction": "inflow"
      }
    },
    "refs": {
      "internal": {
        "txId": "string",
        "sessionId": "string",
        "txRef": "string",
        "resourceId": "string",
        "txDate": "string"
      },
      "external": {
        "txId": "string",
        "sessionId": "string",
        "txRef": "string",
        "resourceId": "string",
        "txDate": "string"
      }
    },
    "trail": [
      {
        "phase": "initiated | completed",
        "status": "success",
        "actor": "user | system | provider",
        "message": "string",
        "meta": {},
        "timestamp": "string"
      }
    ],
    "meta": {},
    "createdAt": "string",
    "updatedAt": "string"
  }
}

​
Transaction Schema

FieldTypeDescription
internalTrackingIdstringInternal transaction identifier
typestringTransaction type
amountnumberTransaction amount
statusstringTransaction status
currencystringCurrency code
narrationstringTransaction description
settlementobjectSettlement information
customerIdstringCustomer identifier
entityIdstringMerchant identifier
bankIdstringBank identifier
feesobjectFee information
partiesobjectTransaction parties
refsobjectReference information
trailarrayTransaction trail
createdAtstringCreation timestamp
updatedAtstringLast update timestamp

​
Transaction Status Types

StatusDescription
completedTransaction successfully processed
pendingTransaction awaiting processing
failedTransaction failed
reversedTransaction was reversed
refundedTransaction was refunded
refunded_partialTransaction was partially refunded

​
Error Responses

​
400 Bad Request

{
  "statusCode": 400,
  "success": false,
  "message": "Either transactionId or internalTrackingId is required"
}

​
404 Not Found

{
  "statusCode": 404,
  "success": false,
  "message": "Transaction not found"
}