Utopia PaymentsDocs
Events

List events

Lists the events recorded for the key's merchant and mode, newest first, whether or not an endpoint was listening when they happened. Filter by `type` to walk one kind. One page carries `items`, `has_more` and `next_cursor`; pass `next_cursor` back as `cursor` for the next page. Use it to catch up on what happened while your endpoint was down, and to reconcile your records against what Utopia sent.

GET
/events

Lists the events recorded for the key's merchant and mode, newest first, whether or not an endpoint was listening when they happened. Filter by type to walk one kind. One page carries items, has_more and next_cursor; pass next_cursor back as cursor for the next page. Use it to catch up on what happened while your endpoint was down, and to reconcile your records against what Utopia sent.

Authorization

secretKey
AuthorizationBearer <token>

Your secret key: sk_live_… or sk_test_….

In: header

Query Parameters

limit?integer

How many records to return in one page: 1 to 100, and 20 when left out. Asking for more than 100 is refused with INVALID_REQUEST.

Range1 <= value <= 100
Default20
cursor?string

The next_cursor of the previous page; leave it out for the first page. A cursor marks the record the next page starts after, so records created while you walk the list never shift the pages you have not read yet. Anything the API did not issue is refused with INVALID_CURSOR.

type?string

Only events of this type, webhook.test included.

Value in

  • "payment.succeeded"
  • "payment.failed"
  • "refund.succeeded"
  • "subscription.active"
  • "subscription.renewed"
  • "subscription.on_hold"
  • "subscription.cancelled"
  • "webhook.test"

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/events"
{  "items": [    {      "object": "event",      "event_id": "evt_3f2b8c1e9a4d4e7b8c2a1d5e6f7a8b9c",      "type": "payment.succeeded",      "livemode": true,      "created_at": "2019-08-24T14:15:22Z",      "data": {}    }  ],  "has_more": true,  "next_cursor": "string"}

Retrieve an event GET

Returns one event, with the object it happened to in `data`. Its id is the value a delivery carries in its `webhook-id` header, so a handler can read the event back from the API before acting on it. Only events belonging to the key's merchant and mode are visible.

Retrieve your account GET

Returns the merchant this key belongs to: the business name and support email customers see, whether the key is a live or a test key (`livemode`), whether card payments are ready (`payments_enabled`), and the currencies new products and carts may be priced in. Call it to confirm a key works and which mode it is in, and read `currencies` before creating a product: a checkout in any other currency is refused with `CURRENCY_NOT_SUPPORTED`. While payments are unavailable the list is empty.