List Transactions

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

string

required

The ID of the customer whose transactions you want to retrieve. Must belong to your merchant account.

number

default:"1"

Page number for pagination. Must be a positive integer.

number

default:"20"

Number of records per page. Must be a positive integer.

string

default:"ALL"

Filter by transaction direction. One of CREDIT, DEBIT, or ALL.

string

Filter by transaction status. Common values: success, pending, failed.

string

Filter by transaction category, such as BANK_TRANSFER or WALLET_TO_WALLET_TRANSFER.

string

ISO 8601 date string. Returns transactions created on or after the start of this date.

string

ISO 8601 date string. Returns transactions created on or before the end of this date.

Response

boolean

true when the request succeeded.

object[]

Array of transaction objects.

Show Transaction object

string

Unique transaction identifier (UUID).

string

Merchant-assigned or system-generated transaction reference.

string

CREDIT or DEBIT.

string

Transaction status: success, pending, or failed.

number

Transaction amount in the smallest currency unit (kobo).

number

Processing fee applied to the transaction.

number

VAT applied to the transaction.

number

Total amount including fees and VAT.

string

Currency code, e.g. NGN.

string

Transaction category, e.g. BANK_TRANSFER, WALLET_TO_WALLET_TRANSFER.

string

Human-readable transaction description.

string

Source account or wallet identifier.

string

Destination account or wallet identifier.

number

Wallet balance immediately before the transaction.

number

Wallet balance immediately after the transaction.

object

Arbitrary key-value metadata attached to the transaction.

string

ISO 8601 timestamp when the transaction was created.

string

ISO 8601 timestamp when the transaction was last updated.

object

Pagination metadata.

Show Pagination

number

Current page number.

number

Total number of matching records.

number

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
  }
}

{
  "status": false,
  "message": "Customer could not be found."
}

List merchant transactions

Retrieve all transactions across your merchant account.

GET https://api.tagpay.ng/v1/merchant/transactions

Query parameters

number

default:"1"

Page number for pagination.

number

default:"20"

Number of records per page.

string

default:"ALL"

Filter by transaction direction: CREDIT, DEBIT, or ALL.

string

Filter by transaction category.

string

ISO 8601 date string for the start of the date range.

string

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

number

default:"1"

Page number for pagination.

number

default:"20"

Number of records per page.

string

default:"ALL"

Filter by direction: CREDIT, DEBIT, or ALL.

string

Filter by transaction category.

string

ISO 8601 date string for the start of the date range.

string

ISO 8601 date string for the end of the date range.

Response

boolean

true when the request succeeded.

object[]

Array of pending transaction objects.

Show Pending transaction object

string

Unique pending transaction ID.

string

CREDIT or DEBIT.

string

Always PENDING for results from this endpoint.

number

Transaction amount in kobo.

string

Transaction category.

object

Arbitrary metadata for the transaction.

object

The user who initiated the transaction.

Show Creator

string

User ID.

string

First name.

string

Last name.

object

The user who approved the transaction, if already approved. null when still pending.

Show Approver

string

User ID.

string

First name.

string

Last name.

string

ISO 8601 creation timestamp.

string

ISO 8601 last-updated timestamp.

object

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

number

default:"1"

Page number for pagination.

number

default:"20"

Number of records per page.

string

default:"ALL"

Filter by direction: CREDIT, DEBIT, or ALL.

string

Filter by transaction category.

string

Search by batch reference string.

string

ISO 8601 date string for the start of the date range.

string

ISO 8601 date string for the end of the date range.

Response

boolean

true when the request succeeded.

object[]

Array of batch transaction objects.

object

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
  }
}

Wallets

Transfers

Transactions

Webhooks

List customer transactions

Query parameters

Response

List merchant transactions

Query parameters

Response

List pending transactions

Query parameters

Response

List batch transactions

Query parameters

Response

​List customer transactions

​Query parameters

​Response

​List merchant transactions

​Query parameters

​Response

​List pending transactions

​Query parameters

​Response

​List batch transactions

​Query parameters

​Response

List customer transactions

Query parameters

Response

List merchant transactions

Query parameters

Response

List pending transactions

Query parameters

Response

List batch transactions

Query parameters

Response