Overview

The Events List API allows you to retrieve transaction status changes for your merchant account. Due to the potentially large volume of events, this API uses a pagination system that returns up to 10,000 events per request.

See Transaction Statuses for descriptions of statuses.

Current Implementation (Per Merchant)

Each API request is specific to a single merchant API key. You must make separate calls for each merchant you manage.

Upcoming Feature (ETA: Q1 2025)

We are rolling out gateway-level API keys that will allow you to retrieve status changes for all merchants under a gateway with a single API call, eliminating the need for multiple merchant-specific requests.

How It Works

Step 1: Initial Request (No Token)

Make your first request without any continuation token. This retrieves the first batch of up to 10,000 transaction events.

Endpoint: GET /events

Headers: Your merchant API key authentication headers

Response includes:

events: Array of transaction status updates (up to 10,000)
new_pointer: Token to use for the next request
exists_more_events: Boolean indicating if more events are available

Step 2: Subsequent Requests (With Token)

If exists_more_events is true, make another request using the new_pointer from the previous response.

Endpoint: GET /events/{new_pointer}

Headers:

Your merchant API key authentication headers

Continue this process until exists_more_events returns false, indicating you have retrieved all available events.

Pagination Workflow

Call GET /events (no token)
Receive up to 10,000 events + new_pointer
Check exists_more_events
1. FALSE` → Done, you have all events
2. TRUE → Call GET /events/{new_pointer}
Repeat steps 2-3 until exists_more_events is false

Recommended Polling Schedule

For optimal event retrieval, we recommend issuing GET requests at the following times (Eastern Time):

11:00 AM ET
5:30 PM ET
7:00 PM ET
10:00 PM ET