DocumentationGET Retrieve a refund
Payments API
GET
/refunds/{id}Retrieve a refund
The refund and the payment it belongs to.
Use your sandbox environment to start. Understand error codes and payment statuses before handling a live payment.
Retrieve a refund
curl --request GET "https://api.veyqo.org/api/v1/refunds/$REFUND_ID" \
--header "Authorization: Bearer $VEYQO_SECRET_KEY" \
--header "Accept: application/json"{
"success": true,
"data": {
"id": "ref_01M6EB66SC61Q3RQYAN0693DGM",
"object": "refund",
"payment": "pay_01M6EB66SC61Q3RQYAN0693DGM",
"amount": 25000,
"currency": "NGN",
"status": "pending",
"reason": "requested_by_customer",
"failure_message": null,
"created_at": "2026-11-02T12:00:00+00:00"
}
}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/refunds/{id}
Server secret key required. Scope: refunds: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- Veyqo refund ID.
object"refund"required- See the JSON example.
paymentstringrequired- Original Veyqo payment ID.
amountintegerrequired- Refund amount in the smallest currency unit.
currencystringrequired- Original payment currency.
statusstringrequired- Values: pending, succeeded, failed.
reasonstring | nullrequired- Optional reason.
failure_messagestring | nullrequired- Provider failure message when available.
created_atstring | nullrequired- ISO 8601 timestamp. Format: date-time.
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. |
| ENVIRONMENT_MISMATCH | 403 | Use the correct sandbox/live key. Resources outside the key’s project remain not-found instead of disclosing ownership. | After selecting the correct key. |