Transaction Management Schemas
API endpoints for monitoring and tracking payment transactions.Endpoints
| Method | Endpoint | Description |
|---|---|---|
| GET | /v1/transaction-history | Get transaction history with filters |
| GET | /v1/transaction-details | Get detailed transaction information |
GET /v1/transaction-history
Retrieve transaction history with extensive filtering and pagination options.Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
page | number | No | Page number for pagination |
limit | number | No | Number of results per page |
search | string | No | Search by name, tracking ID, or fee ID |
status | string | No | Filter by transaction status |
minAmount | number | No | Minimum transaction amount |
maxAmount | number | No | Maximum transaction amount |
startDate | string | No | Start date for date range filter |
endDate | string | No | End date for date range filter |
settlementStatus | string | No | Filter by settlement status |
customerId | string | No | Filter by customer ID |
feeId | string | No | Filter by fee ID |
sortBy | string | No | Field to sort by |
sortOrder | string | No | Sort 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
| Parameter | Type | Required | Description |
|---|---|---|---|
transactionId | string | No | Transaction ID (one of transactionId or internalTrackingId required) |
internalTrackingId | string | No | Internal 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
| Field | Type | Description |
|---|---|---|
internalTrackingId | string | Internal transaction identifier |
type | string | Transaction type |
amount | number | Transaction amount |
status | string | Transaction status |
currency | string | Currency code |
narration | string | Transaction description |
settlement | object | Settlement information |
customerId | string | Customer identifier |
entityId | string | Merchant identifier |
bankId | string | Bank identifier |
fees | object | Fee information |
parties | object | Transaction parties |
refs | object | Reference information |
trail | array | Transaction trail |
createdAt | string | Creation timestamp |
updatedAt | string | Last update timestamp |
Transaction Status Types
| Status | Description |
|---|---|
completed | Transaction successfully processed |
pending | Transaction awaiting processing |
failed | Transaction failed |
reversed | Transaction was reversed |
refunded | Transaction was refunded |
refunded_partial | Transaction 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"
}