Transactions

Transaction Timeline

Retrieve the full event history for a transaction, ordered from earliest to latest.

Transaction Timeline

GET /v1/transactions/:reference/timeline

Returns an ordered list of events recorded against a transaction — from the moment the session was opened through to payment completion, failure, or cancellation.


Request

raw HTTP
npm install @e-pay/node
pip install epay
composer require epay-et/php-sdk
go get github.com/epay-et/go-sdk
curl https://api.e-pay.et/v1/transactions/PAB12CD3420260813/timeline \
  -H "Authorization: Bearer sk_live_your_key_here"
import { Epay } from '@e-pay/node';

const epay = new Epay({ apiKey: process.env.EPAY_SECRET_KEY });

const timeline = await epay.transactions.timeline(reference);

for (const event of timeline.events) {
console.log(event.eventType, event.occurredAt, event.errorCode);
}
const res = await fetch('https://api.e-pay.et/v1/transactions/PAB12CD3420260813/timeline', {
  headers: { Authorization: `Bearer ${process.env.EPAY_SECRET_KEY}` },
});

if (!res.ok) throw new Error(`ePay ${res.status}: ${await res.text()}`);

const { reference, events } = await res.json();
from epay import Epay

epay = Epay() # reads EPAY_SECRET_KEY

timeline = epay.transactions.timeline(reference)

for event in timeline["events"]:
print(event["eventType"], event["occurredAt"], event["errorCode"])
import os
import requests

res = requests.get(
    "https://api.e-pay.et/v1/transactions/PAB12CD3420260813/timeline",
    headers={"Authorization": f"Bearer {os.environ['EPAY_SECRET_KEY']}"},
    timeout=30,
)
res.raise_for_status()

timeline = res.json()
use Epay\Epay;

$epay = new Epay(); // reads EPAY_SECRET_KEY

$timeline = $epay->transactions->timeline($reference);

foreach ($timeline['events'] as $event) {
echo $event['eventType'], ' ', $event['occurredAt'], PHP_EOL;
}
$ch = curl_init('https://api.e-pay.et/v1/transactions/PAB12CD3420260813/timeline');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('EPAY_SECRET_KEY')],
]);

$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

if ($status >= 400) {
    throw new RuntimeException("ePay {$status}: {$body}");
}

$timeline = json_decode($body, true);
timeline, err := client.Transactions.Timeline(ctx, reference)
if err != nil {
	return err
}

for \_, event := range timeline.Events {
log.Println(event.EventType, event.OccurredAt)
}
req, _ := http.NewRequestWithContext(ctx, http.MethodGet, "https://api.e-pay.et/v1/transactions/PAB12CD3420260813/timeline", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("EPAY_SECRET_KEY"))

res, err := http.DefaultClient.Do(req)
if err != nil {
	return err
}
defer res.Body.Close()

if res.StatusCode >= 400 {
	return fmt.Errorf("ePay %d", res.StatusCode)
}

var timeline struct {
	Reference string `json:"reference"`
	Events    []struct {
		EventType    string  `json:"eventType"`
		OccurredAt   string  `json:"occurredAt"`
		ErrorCode    *string `json:"errorCode"`
		ErrorMessage *string `json:"errorMessage"`
	} `json:"events"`
}
if err := json.NewDecoder(res.Body).Decode(&timeline); err != nil {
	return err
}

Completed payment

{
  "reference": "PAB12CD3420260813",
  "events": [
    {
      "eventType": "session_created",
      "occurredAt": "2026-08-13T11:30:00.000Z",
      "errorCode": null,
      "errorMessage": null
    },
    {
      "eventType": "payment_initiated",
      "occurredAt": "2026-08-13T11:45:12.000Z",
      "errorCode": null,
      "errorMessage": null
    },
    {
      "eventType": "payment_completed",
      "occurredAt": "2026-08-13T11:47:00.000Z",
      "errorCode": null,
      "errorMessage": null
    }
  ]
}

Failed payment

{
  "reference": "PFF98AB1220260812",
  "events": [
    {
      "eventType": "session_created",
      "occurredAt": "2026-08-12T09:15:00.000Z",
      "errorCode": null,
      "errorMessage": null
    },
    {
      "eventType": "payment_failed",
      "occurredAt": "2026-08-12T09:18:44.000Z",
      "errorCode": "INSUFFICIENT_FUNDS",
      "errorMessage": "The customer's account does not have sufficient balance."
    }
  ]
}

Path Parameters

Prop

Type


Response

Prop

Type

Event object

Prop

Type


Errors

StatusDescription
401Missing or invalid API key.
404No transaction found for the given reference under your account.

Next: Webhooks — receive payment events in real time instead of polling.

On this page