Transactions

Read any payment, payout or refund, and list them.

Endpoint	What it does
GET /v1/transactions	List transactions
GET /v1/transactions/{id}	Retrieve a transaction

Try any of them in the API tester.

List transactions

GET /v1/transactions

Keyset-paginated, newest first. Pass the paging.next_cursor from one response as cursor on the next.

A date window is always applied: omitting one defaults to the last 30 days, and a window wider than 180 days is refused rather than silently truncated. The applied window is echoed back, so a short result is distinguishable from a short history.

totals is omitted when a filter is applied that the count cannot honour, rather than returning a number that counts a larger set than the page.

Authentication: a secret key (server-side only) with the scope transaction.read.

Parameters

Field	Type	Required	Allowed values and limits	What it is
limit	integer	no	min 1; max 100; default 25	Rows per page. Clamped to 100.
cursor	string	no		The next_cursor from the previous page. Omit for the first page.
created_after	string	no		RFC 3339 timestamp, inclusive. Defaults to 30 days ago. The window may not exceed 180 days.
created_before	string	no		RFC 3339 timestamp, exclusive. Defaults to now.
direction	string	no	One of: collection, payout	collection for money in (charges); payout for money out (payouts and refunds). Omit for both.
channel	string	no	One of: mobile_money, bank, card, ussd, wallet, cash	Only transactions on this channel.
currency	string	no	e.g. GHS	Only transactions in this currency, as an ISO 4217 code.
status	array	no		Repeatable. Any of initiated, pending, processing, awaiting_action, succeeded, failed, cancelled, expired, reversed, refunded, partially_refunded.
min_amount	integer	no	min 0	Minimum gross amount in minor units.
max_amount	integer	no	min 0	Maximum gross amount in minor units.
reference	string	no		PaySigna’s reference, exact match.
merchant_reference	string	no		Your own reference, exact match.
customer_id	string (uuid)	no		Only transactions with this stored customer.
settled	string	no	One of: true, false	Filter on whether the transaction has settled.

Response 200

Field	Type	What it is
data	array
object	string
paging	object
paging.has_more	boolean
paging.limit	integer	The page size actually applied, after clamping.
paging.next_cursor	string	Pass as ?cursor= to fetch the next page. Absent when has_more is false.
totals	object
totals.count	integer
totals.fees	integer	Sum of platform fee and tax, in minor units.
totals.gross	integer	Sum of gross amounts, in minor units.
totals.net	integer	Sum of what was or will be credited to you, in minor units.
window	object
window.created_after	string (date-time)
window.created_before	string (date-time)

Errors

• 401: the key is missing, wrong or revoked
• 403: the key lacks the scope, or your account may not do this
• 422: a field is invalid; errors names it
• 429: too many requests; wait for Retry-After
• 500: Internal Server Error
• 503: the payment partner is unreachable; safe to retry

Every error is a JSON problem with a stable code. See Errors.

---

Retrieve a transaction

GET /v1/transactions/{id}

Reads any transaction, whether a charge, a payout or a refund, in the environment of the key used.

Authentication: a secret key (server-side only) with the scope transaction.read.

Parameters

Field	Type	Required	Allowed values and limits	What it is
{id}	string (uuid)	yes		The transaction’s id. A charge, payout or refund id works here.

Response 200

Field	Type	What it is
action	object
action.attempts_remaining	integer	otp only: how many more incorrect codes are allowed before the charge fails.
action.expires_at	string (date-time)	When the partner stops accepting this action, where it says. For otp, a code sent after this is refused; send a new one first if resendable.
action.message	string	What to tell the customer, when the type alone does not say: for otp, where the code is (e-mailed to them, or shown in their bank’s app). Safe to show as is.
action.resendable	boolean	otp only: the code can be sent to the customer again with POST /v1/charges/{id}/otp/resend.
action.type	string	prompt: the customer approves a prompt on their phone. otp: they enter a one-time code, which you send to POST /v1/charges/{id}/otp. 3ds_redirect or hosted_checkout: send them to url. ussd: they dial a code (reserved, not currently used). One of: prompt, otp, 3ds_redirect, hosted_checkout, ussd
action.url	string	Open this to complete authentication. Absent for a handset prompt.
amount	integer	Gross amount in minor units — 1250 is GHS 12.50.
callback_url	string	The callback URL you sent when creating it.
channel	string	The channel the money moved on, such as mobile_money, bank or card.
completed_at	string (date-time)	When it reached a final state.
counterparty	object
counterparty.masked	string	A partial identifier. The full value is never returned.
counterparty.name	string	The name the merchant supplied.
counterparty.verified_name	string	The name the account or wallet is registered to, when the provider returned one. Compare it with name to spot a mismatch.
created_at	string (date-time)	When the transaction was created.
currency	string	ISO 4217 code of the amounts.
customer_amount	integer	What the customer paid or received, including any fee they bore, in minor units.
description	string	The description you sent when creating it.
direction	string	collection is money in (a charge); payout is money out (a payout or a refund). One of: collection, payout
expires_at	string (date-time)	After this, a transaction still waiting on the customer expires.
failure_class	string	Why it failed, as a category: insufficient_funds, invalid_recipient, limit_exceeded, declined, timeout, transport, partner_unavailable, duplicate, risk_blocked, configuration or internal. Present only on a failure.
failure_code	string	A more specific machine-readable reason, when one is available.
failure_message	string	A readable explanation of the failure.
fee	object
fee.bearer	string	Who paid the fees: merchant (out of merchant_amount) or customer (on top of the amount). One of: merchant, customer
fee.commission	integer	Commission you accepted for a company that referred you, on this payment. Follows bearer, like platform.
fee.platform	integer	PaySigna’s fee, in minor units.
fee.tax	integer	Tax charged on the fee, in minor units.
id	string	The transaction’s id: the same id as the charge, payout or refund it records.
merchant_amount	integer	What this moved on your balance, after fees you bore, in minor units.
metadata	object	The metadata you sent, unchanged.
object	string
parent_transaction_id	string	Set on a refund or a reversal: the transaction it reverses.
reference	string	PaySigna’s reference. Quote it to support.
refunded_amount	integer	How much of this transaction has been refunded, in minor units.
settled_at	string (date-time)	Absent until the funds have settled to us.
settlement	object
settlement.amount	integer	In the settlement currency’s minor units.
settlement.currency	string	The currency you are settled in, as an ISO 4217 code.
status	string	One of initiated, pending, processing, awaiting_action, succeeded, failed, cancelled, expired, reversed, refunded or partially_refunded. reversed means it succeeded and was later clawed back.
submitted_at	string (date-time)	When it was sent for processing.
your_reference	string	The reference you sent when creating it.

Errors

• 401: the key is missing, wrong or revoked
• 403: the key lacks the scope, or your account may not do this
• 404: no such resource on this account
• 422: a field is invalid; errors names it
• 429: too many requests; wait for Retry-After
• 500: Internal Server Error
• 503: the payment partner is unreachable; safe to retry

Every error is a JSON problem with a stable code. See Errors.