List payments

List payments in this project environment, newest first. Only status, reference, created_after, created_before and pagination filters are implemented.

Use with AI

Download Claude instructions Download Codex instructions All AI integration resources

Markdown

GEThttps://api.veyqo.org/api/v1/paymentsTry in console

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

List payments

curl --request GET "https://api.veyqo.org/api/v1/payments?per_page=5" \
  --header "Authorization: Bearer $VEYQO_SECRET_KEY" \
  --header "Accept: application/json"

{
  "success": true,
  "data": [
    {
      "id": "pay_01M6EB66SC61Q3RQYAN0693DGM",
      "object": "payment",
      "reference": "ORDER-1001",
      "status": "pending",
      "amount": 50000,
      "amount_refunded": 0,
      "currency": "NGN",
      "customer": {
        "email": "customer@example.com",
        "name": "Ada Lovelace",
        "phone": null
      },
      "description": "Order 1001",
      "checkout_url": "https://checkout.paystack.com/example",
      "provider": "paystack",
      "provider_reference": "provider_reference_example",
      "metadata": {
        "order_id": "1001"
      },
      "failure_code": null,
      "failure_message": null,
      "authorized_at": null,
      "succeeded_at": null,
      "failed_at": null,
      "created_at": "2026-11-02T12:00:00+00:00"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "has_more": false
  }
}

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/payments

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

Path and query parameters

Parameter	Location	Required	Description
page	query	No	Page number, starting at 1.
per_page	query	No	Page size, default 25 and maximum 100. Maximum 100.
status	query	No	Normalized payment status.
reference	query	No	Exact merchant reference.
created_after	query	No	Inclusive creation-time lower bound. Use an ISO 8601 date/time.
created_before	query	No	Inclusive creation-time upper bound. Use an ISO 8601 date/time.

Response fields

idstringrequired: Globally unique Veyqo payment ID; use it for reconciliation.
object"payment"required: See the JSON example.
referencestringrequired: Merchant reference unique within the project environment; defaults to the payment ID.
statusstringrequired: Normalized payment state. Do not fulfil pending, processing, failed or cancelled payments. Values: created, pending, processing, succeeded, failed, cancelled, refunded, partially_refunded.
amountintegerrequired: Original amount in the smallest currency unit.
amount_refundedintegerrequired: Successfully refunded amount in the smallest currency unit.
currencystringrequired: Three-letter currency code.
customerobjectrequired: See the JSON example.
customer.emailstringrequired: Customer email address.
customer.namestring | nullrequired: Customer name.
customer.phonestring | nullrequired: Customer phone.
descriptionstring | nullrequired: Optional description.
checkout_urlstring | nullrequired: Provider checkout URL for direct payments; may be null depending on the flow. Format: uri.
providerstringrequired: Selected provider slug.
provider_referencestring | nullrequired: Reference the provider assigned, not your order reference.
metadataobject | arrayrequired: Your non-sensitive JSON metadata. Objects are recommended; do not store secrets or card details.
failure_codestring | nullrequired: Machine-readable payment failure reason, separate from API error codes.
failure_messagestring | nullrequired: Human-readable payment failure reason.
authorized_atstring | nullrequired: ISO 8601 timestamp. Format: date-time.
succeeded_atstring | nullrequired: ISO 8601 timestamp. Format: date-time.
failed_atstring | nullrequired: ISO 8601 timestamp. Format: date-time.
created_atstring | nullrequired: ISO 8601 timestamp. Format: date-time.

data is an array; meta contains page, per_page, total and has_more. These public API pagination fields use snake_case.

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.

Complete error catalogue

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