List charge events

GEThttps://api.omise.co/charges/:id/events

Retrieve a paginated list of events for a specific charge. Use this endpoint to monitor charge activity, debug webhooks, and track all events related to a particular charge including creation, completion, refunds, and disputes.

Request Parameters

Required - 1 fieldPath Parameters

▼

`id`STRING(required)

The charge ID to retrieve events for. Charge IDs start with chrg_ followed by test_ for test mode.

Example:"chrg_test_5xuy4w91xqz7d1w9u0t"

Optional - 3 fieldsPagination Parameters

▼

`limit`INTEGER(optional)

Number of events to return per page.

Example:20

Constraints:Minimum: 1, Maximum: 100, Default: 20

Default:20

`offset`INTEGER(optional)

Number of events to skip for pagination. Use with limit to paginate through large result sets.

Example:0

Default:0

`order`STRING(optional)

Sort order of results.

Example:"chronological"

Values:chronological, reverse_chronological

Default:"chronological"

Optional - 2 fieldsFilter Parameters

▼

---

Responses

200

Successful retrieval

Returns a paginated list of event objects for the specified charge. Each event contains complete information about the action that occurred.

Response includes:

• data - Array of event objects related to the charge
• limit - Number of results per page
• offset - Number of skipped results
• total - Total number of events for the charge
• order - Sort order applied

400

Bad request

Request validation failed. Check the error message for details.

Common causes:

• Invalid date format (must be ISO 8601)
• Limit exceeds maximum (100)
• Invalid order parameter

401

Unauthorized

Authentication failed. Invalid or missing API key.

Common causes:

• Missing Authorization header
• Invalid secret key
• Using public key instead of secret key
• Incorrect HTTP Basic Auth format

404

Not found

Charge not found or does not exist.

Common causes:

• Invalid charge ID
• Charge ID from different account
• Mixing test and live mode keys

5xx

Server error

Server-side error occurred. These are rare but should be handled gracefully.

How to handle:

• Retry the request with exponential backoff
• Check status.omise.co for service incidents
• See Error Handling for detailed guidance

---

Code samples

cURL

curl https://api.omise.co/charges/chrg_test_5xuy4w91xqz7d1w9u0t/events \
  -u skey_test_5xuy4w91xqz7d1w9u0t: \
  -G \
  -d limit=20 \
  -d offset=0

Ruby

require 'omise'

Omise.api_key = 'skey_test_5xuy4w91xqz7d1w9u0t'

charge = Omise::Charge.retrieve('chrg_test_5xuy4w91xqz7d1w9u0t')
events = charge.events({
  limit: 20,
  offset: 0
})

Python

import omise

omise.api_secret = 'skey_test_5xuy4w91xqz7d1w9u0t'

charge = omise.Charge.retrieve('chrg_test_5xuy4w91xqz7d1w9u0t')
events = charge.events(
    limit=20,
    offset=0
)

Node.js

const omise = require('omise')({
  secretKey: 'skey_test_5xuy4w91xqz7d1w9u0t'
});

const events = await omise.charges.listEvents('chrg_test_5xuy4w91xqz7d1w9u0t', {
  limit: 20,
  offset: 0
});

PHP

<?php
define('OMISE_SECRET_KEY', 'skey_test_5xuy4w91xqz7d1w9u0t');

$charge = OmiseCharge::retrieve('chrg_test_5xuy4w91xqz7d1w9u0t');
$events = $charge->events(array(
    'limit' => 20,
    'offset' => 0
));

Java

Client client = new Client.Builder()
    .secretKey("skey_test_5xuy4w91xqz7d1w9u0t")
    .build();

ScopedList<Event> events = client.charges()
    .listEvents("chrg_test_5xuy4w91xqz7d1w9u0t")
    .limit(20)
    .offset(0)
    .send();

C#

var client = new Client("skey_test_5xuy4w91xqz7d1w9u0t");

var events = await client.Charges.ListEvents("chrg_test_5xuy4w91xqz7d1w9u0t", new ListRequest
{
    Limit = 20,
    Offset = 0
});

Go

client, _ := omise.NewClient(
    "pkey_test_5xuy4w91xqz7d1w9u0t",
    "skey_test_5xuy4w91xqz7d1w9u0t",
)

events, _ := client.ListChargeEvents("chrg_test_5xuy4w91xqz7d1w9u0t", &operations.ListEvents{
    Limit:  20,
    Offset: 0,
})

---

Error and result codes

Common Error Codes

Code	Description	Resolution
authentication_failure	Invalid API key	Verify your secret key is correct
bad_request	Invalid parameters	Check date format and parameter values
invalid_date_format	Date not in ISO 8601	Use format: YYYY-MM-DDTHH:MM:SSZ
not_found	Charge not found	Check charge ID and ensure correct mode (test/live)

Event Types for Charges

Key	Description
charge.create	Charge created
charge.complete	Charge succeeded
charge.update	Charge updated (e.g., captured, metadata changed)
charge.reverse	Charge reversed
charge.expire	Charge expired
refund.create	Refund processed on the charge
charge.dispute.create	Dispute filed against the charge
charge.dispute.update	Dispute status changed
charge.dispute.close	Dispute resolved

---

🔑API Credentials

▼

Try it out

Required - 1 fields

▼

id(Required)

Your IP: ...Loading...