All list endpoints require a valid Authorization: Bearer <token> header and return results scoped to your merchant account and the current API mode (sandbox or production).
List customer transactions Retrieve the transaction history for a specific customer wallet.
GET https://api.tagpay.ng/v1/transaction/customer
Query parameters The ID of the customer whose transactions you want to retrieve. Must belong to your merchant account.
Page number for pagination. Must be a positive integer.
Number of records per page. Must be a positive integer.
Filter by transaction direction. One of CREDIT, DEBIT, or ALL.
Filter by transaction status. Common values: success, pending, failed.
Filter by transaction category, such as BANK_TRANSFER or WALLET_TO_WALLET_TRANSFER.
ISO 8601 date string. Returns transactions created on or after the start of this date.
ISO 8601 date string. Returns transactions created on or before the end of this date.
Response true when the request succeeded.
Array of transaction objects. Unique transaction identifier (UUID).
Merchant-assigned or system-generated transaction reference.
Transaction status: success, pending, or failed.
Transaction amount in the smallest currency unit (kobo).
Processing fee applied to the transaction.
VAT applied to the transaction.
Total amount including fees and VAT.
Transaction category, e.g. BANK_TRANSFER, WALLET_TO_WALLET_TRANSFER.
Human-readable transaction description.
Source account or wallet identifier.
Destination account or wallet identifier.
Wallet balance immediately before the transaction.
Wallet balance immediately after the transaction.
Arbitrary key-value metadata attached to the transaction.
ISO 8601 timestamp when the transaction was created.
ISO 8601 timestamp when the transaction was last updated.
Pagination metadata. Total number of matching records.
Total number of pages at the current perPage size.
curl --request GET \ --url "https://api.tagpay.ng/v1/transaction/customer?customerId=cust_abc123&page=1&perPage=20&type=DEBIT" \ --header "Authorization: Bearer <token>"
{ "status" : true , "transactions" : [ { "id" : "a1b2c3d4-e5f6-7890-abcd-ef1234567890" , "reference" : "TXN-20240401-001" , "type" : "DEBIT" , "status" : "success" , "amount" : 500000 , "fee" : 1000 , "vat" : 75 , "total" : 501075 , "currency" : "NGN" , "category" : "BANK_TRANSFER" , "description" : "Transfer to Access Bank" , "source" : "wallet_001" , "destination" : "0123456789" , "balance_before" : 1000000 , "balance_after" : 498925 , "metadata" : {}, "createdAt" : "2024-04-01T10:30:00.000Z" , "updatedAt" : "2024-04-01T10:30:05.000Z" } ], "metadata" : { "page" : 1 , "totalRecords" : 84 , "totalPages" : 5 } }
List merchant transactions Retrieve all transactions across your merchant account.
GET https://api.tagpay.ng/v1/merchant/transactions
Query parameters Page number for pagination.
Number of records per page.
Filter by transaction direction: CREDIT, DEBIT, or ALL.
Filter by transaction category.
ISO 8601 date string for the start of the date range.
ISO 8601 date string for the end of the date range.
Response The response shape mirrors the customer transactions endpoint. The transactions array contains the same transaction object structure. The metadata object contains page, totalRecords, and totalPages.
curl --request GET \ --url "https://api.tagpay.ng/v1/merchant/transactions?page=1&perPage=20&type=ALL&startDate=2024-01-01&endDate=2024-04-30" \ --header "Authorization: Bearer <token>"
{ "status" : true , "transactions" : [ { "id" : "b2c3d4e5-f6a7-8901-bcde-f12345678901" , "reference" : "TXN-20240401-002" , "type" : "CREDIT" , "status" : "success" , "amount" : 2000000 , "fee" : 0 , "vat" : 0 , "total" : 2000000 , "currency" : "NGN" , "category" : "ACCOUNT_FUNDED" , "description" : "Wallet funding" , "createdAt" : "2024-04-01T09:00:00.000Z" , "updatedAt" : "2024-04-01T09:00:02.000Z" } ], "metadata" : { "page" : 1 , "totalRecords" : 312 , "totalPages" : 16 } }
List pending transactions Retrieve transactions that are awaiting approval. Only transactions at or above your user’s configured approvalLimit are returned.
GET https://api.tagpay.ng/v1/transaction/pending
Query parameters Page number for pagination.
Number of records per page.
Filter by direction: CREDIT, DEBIT, or ALL.
Filter by transaction category.
ISO 8601 date string for the start of the date range.
ISO 8601 date string for the end of the date range.
Response true when the request succeeded.
Array of pending transaction objects. Show Pending transaction object
Unique pending transaction ID.
Always PENDING for results from this endpoint.
Transaction amount in kobo.
Arbitrary metadata for the transaction.
The user who initiated the transaction. The user who approved the transaction, if already approved. null when still pending. ISO 8601 creation timestamp.
ISO 8601 last-updated timestamp.
Pagination metadata with page, totalRecords, and totalPages.
curl --request GET \ --url "https://api.tagpay.ng/v1/transaction/pending?page=1&perPage=20" \ --header "Authorization: Bearer <token>"
{ "status" : true , "data" : [ { "id" : "c3d4e5f6-a7b8-9012-cdef-123456789012" , "type" : "DEBIT" , "status" : "PENDING" , "amount" : 10000000 , "category" : "BANK_TRANSFER" , "metadata" : { "accountNumber" : "0123456789" , "bankCode" : "044" }, "creator" : { "id" : "usr_001" , "firstName" : "Amara" , "lastName" : "Okonkwo" }, "approvedBy" : null , "createdAt" : "2024-04-02T08:15:00.000Z" , "updatedAt" : "2024-04-02T08:15:00.000Z" } ], "metadata" : { "page" : 1 , "totalRecords" : 3 , "totalPages" : 1 } }
List batch transactions Retrieve batch transaction records. A batch groups multiple individual transfers initiated together.
GET https://api.tagpay.ng/v1/transaction/batch
Query parameters Page number for pagination.
Number of records per page.
Filter by direction: CREDIT, DEBIT, or ALL.
Filter by transaction category.
Search by batch reference string.
ISO 8601 date string for the start of the date range.
ISO 8601 date string for the end of the date range.
Response true when the request succeeded.
Array of batch transaction objects.
Pagination metadata with page, totalRecords, and totalPages.
curl --request GET \ --url "https://api.tagpay.ng/v1/transaction/batch?page=1&perPage=20&type=DEBIT" \ --header "Authorization: Bearer <token>"
{ "status" : true , "data" : [ { "id" : "d4e5f6a7-b8c9-0123-defa-234567890123" , "reference" : "BATCH-20240401-001" , "type" : "DEBIT" , "status" : "success" , "totalAmount" : 5000000 , "totalCount" : 10 , "category" : "BATCH_BANK_TRANSFER" , "createdAt" : "2024-04-01T14:00:00.000Z" , "updatedAt" : "2024-04-01T14:05:30.000Z" } ], "metadata" : { "page" : 1 , "totalRecords" : 7 , "totalPages" : 1 } }
