Chapa Developer Documentation

View detailed history of state changes and lifecycle events for payments and payouts.

Transaction Logs provide a detailed history of state changes and lifecycle events for a specific payment or payout.

They are especially useful for:

Debugging payment issues
Auditing transaction behavior
Understanding why a transaction failed, was cancelled, or blocked
Customer support and dispute resolution

While All Payments shows the current snapshot, Transaction Logs show how the transaction got there.

What Are Transaction Logs?

A transaction log records each significant event that occurs during a transaction's lifecycle, such as:

Initialization
Authentication required
Payment success or failure
Cancellation
Refunds (partial or full)
Blocking due to compliance or risk rules

Logs are typically derived from:

Internal lifecycle events
Webhook events
Status transitions (e.g. pending → auth_needed → success → refunded)

Common Log Events

Transaction logs usually reflect the same lifecycle states defined in Chapa's standardized status codes:

Status	Meaning
`pending`	Transaction initiated
`success`	Completed successfully
`failed`	Failed or rejected
`cancelled`	Cancelled by user or system
`incomplete`	Timed out or abandoned
`partially_refunded`	Partially refunded
`fully_refunded`	Fully refunded
`auth_needed`	Additional authentication required
`blocked`	Blocked due to risk or compliance

Typical Log Fields

A transaction log entry usually includes:

Field	Description
`reference`	Chapa or merchant reference
`previous_status`	Status before the event
`current_status`	Status after the event
`event`	Triggering event name
`reason`	Failure / block / cancellation reason (if any)
`source`	Origin of event (`API`, `webhook`, `system`)
`created_at`	Timestamp of the event

Example Transaction Logs

Authentication Required:

{
  "reference": "CHAPA123456789",
  "previous_status": "pending",
  "current_status": "auth_needed",
  "event": "payment.auth_needed",
  "reason": "PIN_REQUIRED",
  "source": "system",
  "created_at": "2025-11-07T12:01:00Z"
}

Payment Success:

{
  "reference": "CHAPA123456789",
  "previous_status": "auth_needed",
  "current_status": "success",
  "event": "payment.success",
  "source": "webhook",
  "created_at": "2025-11-07T12:03:10Z"
}

How Merchants Should Use Logs

Debugging Failed Payments

Check the last log entry
Look for reason fields (e.g. INSUFFICIENT_FUNDS, COMPLIANCE_REVIEW)
Identify whether failure was user-driven, system-driven, or compliance-related

Customer Support Investigations

Logs help answer questions like:

Did the customer attempt payment?
Did authentication fail?
Was the transaction cancelled or blocked?
Did the customer retry multiple times?

Auditing & Compliance

Maintain a full timeline of transaction activity
Useful for dispute handling and internal reviews
Helps demonstrate traceability and decision history

Relationship with Webhooks

Each webhook event can be thought of as creating or updating a transaction log entry.

Webhook Event	Log Entry
`payment.failed`	Log entry with `current_status = failed`
`payment.partially_refunded`	Log entry with refund details
`payout.blocked`	Log entry with compliance reason

Best practice: Store webhook payloads or normalize them into log records for traceability.

Best Practices

Store logs in an append-only format
Never overwrite historical log entries
Link logs to both chapa_reference and merchant_reference
Include reason and source whenever available
Treat logs as read-only audit data

Next Steps

All Payments - List and filter all payments
Verify Payments - Confirm individual payment status
Webhooks - Handle payment events in real-time

Transaction Logs

On this page