Skip to content
YusrDocs

API reference

Events

Every notification Yusr sends is recorded as an event. Use the event log to audit deliveries, catch up after downtime, or redeliver an event to your endpoints.

Events endpoints
get/v1/eventsList events
get/v1/events/{id}Retrieve an event
post/v1/events/{id}/resendResend an event to your webhook endpoints

Read the Webhooks guide for the concepts behind these endpoints.

List events

get/v1/events

Query parameters

Query parameters
typestring

One of transaction.paid, transaction.underpaid, transaction.overpaid, transaction.expired, transaction.late_payment, transaction.reversed, transaction.cancelled, settlement.completed

transactionstring
limitinteger

1–100, default 20

starting_afterstring

Cursor: the next_cursor from the previous page.

curl "https://api.yusr.ng/v1/events?type=transaction.paid&limit=20" \
  -H "Authorization: Bearer sk_test_..."

Responses

200A page of events
Show response attributes
Response attributes
objectstringrequired

always "list"

dataarray of objectrequired
Show child attributes
idstringrequired
objectstringrequired

always "event"

typestringrequired

One of transaction.paid, transaction.underpaid, transaction.overpaid, transaction.expired, transaction.late_payment, transaction.reversed, transaction.cancelled, settlement.completed

modestringrequired

One of test, live

created_atstringrequired
dataobject of anyrequired
has_morebooleanrequired
next_cursorstring | nullrequired
Response 200
{
  "object": "list",
  "data": [
    {
      "id": "evt_01JA9QB2V8K1M3N5P7Q9R2S4T6",
      "object": "event",
      "type": "transaction.paid",
      "mode": "live",
      "created_at": "2026-10-06T14:07:12.000Z",
      "data": {
        "transaction": {
          "id": "txn_01JA9Q3K7M2VXR8D5N0B4C6E2F",
          "object": "transaction",
          "mode": "live",
          "status": "paid",
          "amount": 2500000,
          "amount_received": 2500000,
          "fee": 37500,
          "fee_bearer": "merchant",
          "net_amount": 2462500,
          "currency": "NGN",
          "reference": "order-1042",
          "description": "Order #1042",
          "customer": {
            "name": "Ada Obi",
            "email": "ada@example.com",
            "phone": null
          },
          "payment": {
            "account_number": "9912345678",
            "bank_name": "Partner Bank",
            "account_name": "ACME STORES / YUSR",
            "amount": 2500000,
            "expires_at": "2026-10-06T14:30:00.000Z"
          },
          "flags": {
            "overpaid": false,
            "underpaid": false,
            "late": false
          },
          "payments": [
            {
              "id": "pay_01JA9QB2T3W4X5Y6Z7A8B9C0D1",
              "amount": 2500000,
              "payer_name": "ADA OBI",
              "payer_bank": "Partner Bank",
              "payer_account_number": "******4321",
              "received_at": "2026-10-06T14:07:12.000Z"
            }
          ],
          "metadata": {
            "cart_id": "c_88"
          },
          "created_at": "2026-10-06T14:00:00.000Z",
          "updated_at": "2026-10-06T14:07:12.000Z",
          "paid_at": "2026-10-06T14:07:12.000Z",
          "expires_at": "2026-10-06T14:30:00.000Z"
        }
      }
    }
  ],
  "has_more": false,
  "next_cursor": null
}
Error responses
StatusMeaningError codes
401Authentication failedauthentication_failed
Try it in the sandbox

Retrieve an event

get/v1/events/{id}

Path parameters

Path parameters
idstringrequired
curl "https://api.yusr.ng/v1/events/evt_01JA9QB2V8K1M3N5P7Q9R2S4T6" \
  -H "Authorization: Bearer sk_test_..."

Responses

200Event
Show response attributes
Response attributes
idstringrequired
objectstringrequired

always "event"

typestringrequired

One of transaction.paid, transaction.underpaid, transaction.overpaid, transaction.expired, transaction.late_payment, transaction.reversed, transaction.cancelled, settlement.completed

modestringrequired

One of test, live

created_atstringrequired
dataobject of anyrequired
Response 200
{
  "id": "evt_01JA9QB2V8K1M3N5P7Q9R2S4T6",
  "object": "event",
  "type": "transaction.paid",
  "mode": "live",
  "created_at": "2026-10-06T14:07:12.000Z",
  "data": {
    "transaction": {
      "id": "txn_01JA9Q3K7M2VXR8D5N0B4C6E2F",
      "object": "transaction",
      "mode": "live",
      "status": "paid",
      "amount": 2500000,
      "amount_received": 2500000,
      "fee": 37500,
      "fee_bearer": "merchant",
      "net_amount": 2462500,
      "currency": "NGN",
      "reference": "order-1042",
      "description": "Order #1042",
      "customer": {
        "name": "Ada Obi",
        "email": "ada@example.com",
        "phone": null
      },
      "payment": {
        "account_number": "9912345678",
        "bank_name": "Partner Bank",
        "account_name": "ACME STORES / YUSR",
        "amount": 2500000,
        "expires_at": "2026-10-06T14:30:00.000Z"
      },
      "flags": {
        "overpaid": false,
        "underpaid": false,
        "late": false
      },
      "payments": [
        {
          "id": "pay_01JA9QB2T3W4X5Y6Z7A8B9C0D1",
          "amount": 2500000,
          "payer_name": "ADA OBI",
          "payer_bank": "Partner Bank",
          "payer_account_number": "******4321",
          "received_at": "2026-10-06T14:07:12.000Z"
        }
      ],
      "metadata": {
        "cart_id": "c_88"
      },
      "created_at": "2026-10-06T14:00:00.000Z",
      "updated_at": "2026-10-06T14:07:12.000Z",
      "paid_at": "2026-10-06T14:07:12.000Z",
      "expires_at": "2026-10-06T14:30:00.000Z"
    }
  }
}
Error responses
StatusMeaningError codes
401Authentication failedauthentication_failed
404Not foundnot_found
Try it in the sandbox

Resend an event to your webhook endpoints

post/v1/events/{id}/resend

Path parameters

Path parameters
idstringrequired

Request bodyapplication/json

Request body attributes
endpoint_idstring
curl -X POST "https://api.yusr.ng/v1/events/evt_01JA9QB2V8K1M3N5P7Q9R2S4T6/resend" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{}'

Responses

200Queued
Show response attributes
Response attributes
objectstringrequired

always "resend"

queuedintegerrequired

Number of deliveries queued

Response 200
{
  "object": "resend",
  "queued": 1
}
Error responses
StatusMeaningError codes
400Invalid requestinvalid_request
401Authentication failedauthentication_failed
404Not foundnot_found
Try it in the sandbox