Retrieve an event

The normalized event, identical in shape whichever provider caused it.

Use with AI

Download Claude instructions Download Codex instructions All AI integration resources

Markdown

GEThttps://api.veyqo.org/api/v1/events/{id}Integration guide

Use your sandbox environment to start. Understand error codes and payment statuses before handling a live payment.

Retrieve an event

curl --request GET "https://api.veyqo.org/api/v1/events/$EVENT_ID" \
  --header "Authorization: Bearer $VEYQO_SECRET_KEY" \
  --header "Accept: application/json"

{
  "success": true,
  "data": {
    "id": "evt_01M6EB66SC61Q3RQYAN0693DGM",
    "type": "payment.succeeded",
    "created_at": "2026-11-02T12:00:00+00:00",
    "environment": "sandbox",
    "data": {
      "payment_id": "pay_01M6EB66SC61Q3RQYAN0693DGM",
      "reference": "ORDER-1001",
      "amount": 50000,
      "amount_refunded": 0,
      "currency": "NGN",
      "status": "succeeded",
      "customer": {
        "email": "customer@example.com",
        "name": "Ada Lovelace"
      },
      "provider": {
        "name": "paystack",
        "reference": "provider_reference_example"
      },
      "metadata": {
        "order_id": "1001"
      }
    }
  }
}

Illustrative examples. Replace IDs and environment variables with your own values. Keep secret keys on your server.

Headers

Authorizationstringrequired: Bearer <secret-key>. This key determines your project environment and must stay on your server.
Acceptstringoptional: application/json

Endpoint

GET https://api.veyqo.org/api/v1/events/{id}

Server secret key required. Scope: events:read. The key determines the project and environment; no project-selection header is accepted.

Path and query parameters

Parameter	Location	Required	Description
id	path	Yes	Use the ID returned when this resource was created.

Response fields

idstringrequired: Deduplication key: the same ID as Veyqo-Event-Id.
typestringrequired: Normalized event type; see the webhook guide.
created_atstringrequired: Event creation timestamp. Format: date-time.
environmentstringrequired: Values: sandbox, live.
dataEventDatarequired: Payment snapshot when this event was recorded. Refund events also include refund_id and refund_amount.
data.payment_idstringrequired: Payment ID to retrieve and verify.
data.referencestringrequired: Merchant reference.
data.amountintegerrequired: Original minor-unit amount.
data.amount_refundedintegerrequired: Minor-unit refunded amount.
data.currencystringrequired: See the JSON example.
data.statusstringrequired: Values: created, pending, processing, succeeded, failed, cancelled, refunded, partially_refunded.
data.customerobjectrequired: See the JSON example.
data.customer.emailstringrequired: See the JSON example.
data.customer.namestringoptional: See the JSON example.
data.providerobjectrequired: See the JSON example.
data.provider.namestringrequired: Provider slug.
data.provider.referencestring | nullrequired: Provider reference.
data.metadataobject | arrayrequired: Your non-sensitive JSON metadata. Objects are recommended; do not store secrets or card details.
data.refund_idstringoptional: Present for refund events.
data.refund_amountintegeroptional: Present for refund events, in minor units.
data.refund_statusstringoptional: Present for refund events. Values: pending, succeeded, failed.
data.reasonstring | nulloptional: Present for refund events.

Errors and recovery

Code	HTTP	Recovery	Retry policy
INVALID_API_KEY	401	Use a current kc_test_ or kc_live_ secret key on /api/v1. Use a pk_test_ or pk_live_ publishable key only on browser checkout.	After fixing credentials.
INSUFFICIENT_PERMISSION	403	Grant the required scope or use a suitably scoped key. Dashboard organization roles and staff permissions are separate.	After permission changes.
RATE_LIMIT_EXCEEDED	429	Honor Retry-After, use bounded exponential backoff with jitter, and reduce concurrent requests. Read X-RateLimit headers.	Yes, after Retry-After; preserve write idempotency.
METHOD_NOT_ALLOWED	405	Use the method documented for the endpoint, such as POST for verification and refunds.	After fixing the method.
INTERNAL_ERROR	500	Record X-Request-Id, timestamp and sanitized request context. Reconcile unknown payment outcomes before retrying a write; contact support if it persists.	Safe reads: bounded backoff. Writes: reconcile first.
RESOURCE_NOT_FOUND	404	Check the ID, project and environment. Do not guess another project’s IDs. An inactive payment link is also not-found.	No blind retry.

Complete error catalogue

Every Veyqo error code, including which surface emits it and how to recover.