Like every V4 call, this endpoint family expects the three auth factors: a Bearer token (Authorization: Bearer …), a whitelisted source IP, and the per-request RSA signature headers (X-PP-Signature, X-PP-Nonce, X-PP-Timestamp). See Request Signing.

Returns the current state of one transaction — collection or payout — looked up by your reference. Read-only and ledger-derived: what you see here is what the books hold. Use it after a missed webhook or to confirm a payment before releasing goods.

Status vocabulary

The vocabulary matches the write endpoints and webhook event types exactly — completed here is the same state that fired collection.completed.

Example

curl https://v4api.pokeapay.com/api/v4/transactions/INV-2026-0042 \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-PP-Signature: $SIG" -H "X-PP-Nonce: $NONCE" -H "X-PP-Timestamp: $TS"

Response — 200 (collection)

{
  "type": "collection",
  "reference": "INV-2026-0042",
  "status": "completed",
  "amount_minor": 25000,
  "currency": "KES",
  "channel": "mpesa",
  "counterparty": "254712345678",
  "rail_reference": "SGR7XKQ2MP",
  "fee_minor": 500,
  "failure_reason": null,
  "created_at": "2026-07-21T12:00:04+00:00",
  "updated_at": "2026-07-21T12:00:31+00:00"
}

Response — 200 (payout)

{
  "type": "payout",
  "reference": "PAY-2026-0107",
  "status": "completed",
  "amount_minor": 500000,
  "currency": "KES",
  "channel": "mpesa",
  "counterparty": "254711000001",
  "fee_minor": 10000,
  "failure_reason": null,
  "decided_at": "2026-07-21T09:14:02+00:00",
  "created_at": "2026-07-21T09:02:11+00:00",
  "updated_at": "2026-07-21T09:14:02+00:00"
}

• fee_minor is the actual fee from the posted ledger entry — null until money has posted.
• failure_reason is set on failed collections and rejected payouts.
• Unknown reference (or another merchant's) → 404 {"error":"not_found"}.