TagPayTagPay

API Reference

Transactions

A Transaction is the record of a completed (or attempted) charge — it is what the merchant sees in their dashboard, what gets settled, and what gets refunded against. Use these endpoints to list, filter, and retrieve transactions.

List transactions

GET/v1/transactions

Returns a paginated list of transactions, newest first. Combine the date range, status, channel, and amount filters to narrow results.

Default page size is 25, max 100. Use page and per_page to walk the result set.

Query parameters

fromstringoptional

ISO-8601 date or timestamp. Inclusive lower bound on created_at.

tostringoptional

ISO-8601 date or timestamp. Inclusive upper bound on created_at.

statusenum<'success' | 'failed' | 'pending'>optional

Filter by final transaction status.

Allowed: 'success''failed''pending'

channelenum<'card' | 'bank_transfer' | 'ussd'>optional

Filter by the payment channel used by the customer.

Allowed: 'card''bank_transfer''ussd'

customer_emailstringoptional

Filter by the email supplied at charge creation. Exact match.

min_amountintegeroptional

Minimum amount in kobo (inclusive).

max_amountintegeroptional

Maximum amount in kobo (inclusive).

pageintegeroptional

1-indexed page number. Defaults to 1.

per_pageintegeroptional

Results per page. Defaults to 25, max 100.

Response

200
dataarray<Transaction>

List of transactions, newest first.

idstring

Transaction ID (`txn_…`).

referencestring

Charge reference this transaction was created from.

amountinteger

Amount in kobo.

statusenum<'success' | 'failed' | 'pending'>

Final status.

channelstring

Channel used: `card`, `bank_transfer`, or `ussd`.

created_atstring

ISO-8601 timestamp the transaction was opened.

paid_atstring | null

ISO-8601 timestamp the transaction succeeded, or `null`.

customerobject

Customer details captured at charge time.

emailstring

Customer email.

metaobject

Pagination metadata.

totalinteger

Total matching transactions.

pageinteger

Current page number.

per_pageinteger

Page size used for this response.

Errors

INVALID_DATE_RANGE400`from` must be before `to` and both must be valid ISO-8601.
UNAUTHORIZED401API key missing or invalid.

Retrieve a transaction

GET/v1/transactions/:id

Returns the full transaction object. Use the transaction id (not the charge reference) when calling this endpoint.

Path parameters

idstringrequired

Transaction identifier (txn_…).

Response

200
idstring

Transaction ID.

referencestring

Originating charge reference.

amountinteger

Amount in kobo.

statusenum<'success' | 'failed' | 'pending'>

Final status.

channelstring

Channel used by the customer.

created_atstring

ISO-8601 creation timestamp.

paid_atstring | null

ISO-8601 timestamp of successful payment, or `null`.

customerobject

Customer captured at charge time.

emailstring

Customer email.

Errors

NOT_FOUND404No transaction with that ID.