Transaction Report API

1 Base URL

All API requests should be made to the following base URL:

https://paydirect-service.k8.isw.la/api

2 Endpoint

GET /payment-report

Retrieves paginated transaction records based on the supplied filters. Results are restricted to transactions belonging to the authenticated bank.

3 Authentication

This API uses Bearer Token Authentication. Obtain an access token using your client credentials, then include it in the Authorization header of all subsequent requests.

⚠️ Bank-Scoped Access

Access tokens are scoped to the requesting bank and cannot be used to retrieve transactions belonging to other banks.

Get Access Token

cURL Node.js Python

curl --location 'https://passport.k8.isw.la/passport/oauth/token'   --header 'Content-Type: application/x-www-form-urlencoded'   --header 'Authorization: Basic {base64_encoded_credentials}'   --data-urlencode 'grant_type=client_credentials'   --data-urlencode 'scope=profile'

const axios = require('axios');

const credentials = Buffer.from(
  `${clientId}:${clientSecret}`
).toString('base64');

const response = await axios.post(
  'https://passport.k8.isw.la/passport/oauth/token',
  new URLSearchParams({
    grant_type: 'client_credentials',
    scope: 'profile'
  }),
  {
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      'Authorization': `Basic ${credentials}`
    }
  }
);

const accessToken = response.data.access_token;

import requests
import base64

credentials = base64.b64encode(
    f"{client_id}:{client_secret}".encode()
).decode()

response = requests.post(
    'https://passport.k8.isw.la/passport/oauth/token',
    headers={
        'Content-Type': 'application/x-www-form-urlencoded',
        'Authorization': f'Basic {credentials}'
    },
    data={
        'grant_type': 'client_credentials',
        'scope': 'profile'
    }
)

access_token = response.json()['access_token']

Using the Token

Include the access token in the Authorization header of all API requests:

                    Header
                
Authorization: Bearer <access_token>

4 Request Parameters

Pass the following query parameters to filter and paginate your transaction report:

Parameter	Type	Required	Description
StartDate	string	Required	Start date for transaction search (format: `YYYY-MM-DD`)
EndDate	string	Required	End date for transaction search (format: `YYYY-MM-DD`)
PageNumber	integer	Required	Page number for paginated response (starts at 1)
PageSize	integer	Required	Number of records per page
ProductId	integer	Optional	Unique identifier for the product
PaymentChannelId	integer	Optional	Payment channel identifier
CustomerId	string	Optional	Customer unique identifier
PaymentReference	string	Optional	Transaction payment reference

5 Sample Request

Retrieve transactions for a specific product within a date range:

cURL Node.js Python

curl --location 'https://paydirect-service.k8.isw.la/api/payment-report?ProductId=13&StartDate=2024-01-01&EndDate=2026-01-01&PageNumber=1&PageSize=30'   --header 'Authorization: Bearer <access_token>'

const axios = require('axios');

const response = await axios.get(
  'https://paydirect-service.k8.isw.la/api/payment-report',
  {
    headers: {
      'Authorization': `Bearer ${accessToken}`
    },
    params: {
      ProductId: 13,
      StartDate: '2024-01-01',
      EndDate: '2026-01-01',
      PageNumber: 1,
      PageSize: 30
    }
  }
);

console.log(response.data);

import requests

response = requests.get(
    'https://paydirect-service.k8.isw.la/api/payment-report',
    headers={
        'Authorization': f'Bearer {access_token}'
    },
    params={
        'ProductId': 13,
        'StartDate': '2024-01-01',
        'EndDate': '2026-01-01',
        'PageNumber': 1,
        'PageSize': 30
    }
)

print(response.json())

6 Responses

Successful Response

200 OK

                        JSON
                    
{
  "message": "Success",
  "pageNumber": 1,
  "pageSize": 5,
  "totalCount": 28,
  "totalPages": 6,
  "records": [
    {
      "bankCode": "018",
      "paymentReference": "PBL|Web|3pbl0001|MCU2|280825222716|9AN8TVNXVW",
      "customerId": "0000000001",
      "receiptNo": "2501140586",
      "customerName": "ACN",
      "amount": 50000.0000,
      "paymentMethod": "Debit Card",
      "bank": "First Bank of Nigeria Plc",
      "paymentDate": "2025-08-28T22:27:17.55"
    },
    {
      "bankCode": "018",
      "paymentReference": "PBL|Web|3pbl0001|MCU2|280825222154|XC9YHHKVVN",
      "customerId": "0000000001",
      "receiptNo": "2501140585",
      "customerName": "ACN",
      "amount": 50000.0000,
      "paymentMethod": "Debit Card",
      "bank": "First Bank of Nigeria Plc",
      "paymentDate": "2025-08-28T22:21:55.027"
    },
    {
      "bankCode": "018",
      "paymentReference": "PBL|Web|3pbl0001|MCU2|250625234325|JRRK8VUPCF",
      "customerId": "0000000001",
      "receiptNo": "2501137696",
      "customerName": "ACN",
      "amount": 30000000.0000,
      "paymentMethod": "Debit Card",
      "bank": "First Bank of Nigeria Plc",
      "paymentDate": "2025-06-25T23:43:29.68"
    },
    {
      "bankCode": "018",
      "paymentReference": "PBL|Web|3pbl0001|MCU2|250625234125|H49H7FWJY7",
      "customerId": "0000000001",
      "receiptNo": "2501137695",
      "customerName": "ACN",
      "amount": 30000000.0000,
      "paymentMethod": "Debit Card",
      "bank": "First Bank of Nigeria Plc",
      "paymentDate": "2025-06-25T23:41:28.787"
    },
    {
      "bankCode": "018",
      "paymentReference": "PBL|Web|3pbl0001|MCU2|250625234003|ERUQ9CCTTC",
      "customerId": "0000000001",
      "receiptNo": "2501137694",
      "customerName": "ACN",
      "amount": 30000000.0000,
      "paymentMethod": "Debit Card",
      "bank": "First Bank of Nigeria Plc",
      "paymentDate": "2025-06-25T23:40:07.567"
    }
  ]
}

No Transactions Found

200 OK

                        JSON
                    
{
  "status": false,
  "message": "No transaction found",
  "data": {
    "totalRecords": 0,
    "pageNumber": 1,
    "pageSize": 30,
    "totalPages": 0,
    "transactions": []
  }
}

Unauthorized Access

401 Unauthorized

Returned when the access token is missing, invalid, or expired. Obtain a new token and retry the request.

7 Response Fields

Each transaction record in the response contains the following fields:

Field	Type	Description
paymentReference	string	Unique transaction reference
paymentDate	datetime	Date and time payment was processed (ISO 8601 format)
customerId	string	Customer unique identifier
receiptNo	string	Generated receipt number
customerName	string	Name of customer
amount	decimal	Transaction amount
paymentMethod	string	Payment method used (e.g., "Debit Card")
bank	string	Bank processing the transaction
bankCode	string	CBN bank code

8 Business Rules

Only authenticated banks with valid access tokens can access the API
Transactions returned are restricted to the authenticated bank only — cross-bank access is prohibited
Access tokens are bank-scoped and cannot retrieve records belonging to another bank
The API returns only transactions matching the supplied filters
Pagination metadata (totalCount, totalPages) is included in all responses
If no transactions match the criteria, a "No transaction found" message is returned

9 Security

🔒 Security Requirements

All requests must be made over HTTPS
Access tokens must be kept secure and confidential — never expose in client-side code
Tokens are restricted to the bank resource associated with the authenticated client
Implement token refresh logic before expiration to maintain uninterrupted access

10 Pagination

The API supports pagination using PageNumber and PageSize parameters. Use the response metadata to navigate through results:

💡 Pagination Example

To retrieve page 2 with 30 records per page:
?PageNumber=2&PageSize=30

Response Field	Description
pageNumber	Current page number
pageSize	Number of records per page
totalCount	Total number of records matching the criteria
totalPages	Total number of pages available