# Verify a payment Asks the provider what actually happened and updates the payment. Use it when a webhook has not arrived — never trust a browser redirect alone. ## Endpoint POST https://api.veyqo.org/api/v1/payments/{id}/verify Server secret key required. Scope: payments:read. The key determines the project and environment; no project-selection header is accepted. > Do not reuse an idempotency key across verification polls. Every poll should retrieve fresh state. ## Path and query parameters | Parameter | Location | Required | Description | | --- | --- | --- | --- | | id | path | Yes | Veyqo payment ID or URL-encoded merchant reference. Prefer the Veyqo ID for unambiguous lookup. | ## Example request Examples use illustrative IDs and provider URLs. Replace path variables with IDs returned by your own requests. Never paste a live secret into client code or a public tool. ### cURL ```bash curl --request POST "https://api.veyqo.org/api/v1/payments/$PAYMENT_ID/verify" \ --header "Authorization: Bearer $VEYQO_SECRET_KEY" \ --header "Accept: application/json" ``` ### Node.js ```javascript // Server-side Node.js 18+. Save operation.idempotencyKey before a write. const response = await fetch(`https://api.veyqo.org/api/v1/payments/${encodeURIComponent(process.env.PAYMENT_ID)}/verify`, { method: 'POST', headers: { "Authorization": `Bearer ${process.env.VEYQO_SECRET_KEY}`, "Accept": "application/json" }, }); const result = await response.json(); if (!response.ok || !result.success) { console.error(response.status, result.error?.code, response.headers.get('X-Request-Id')); throw new Error(result.error?.message ?? 'Veyqo request failed'); } console.log(result.data); ``` ### PHP ```php 'POST', CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 30, CURLOPT_HTTPHEADER => [ 'Authorization: Bearer '.getenv('VEYQO_SECRET_KEY'), 'Accept: application/json' ], ]); $body = curl_exec($curl); if ($body === false) throw new RuntimeException(curl_error($curl)); $status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE); curl_close($curl); $result = json_decode($body, true, 512, JSON_THROW_ON_ERROR); if ($status >= 400 || !($result['success'] ?? false)) { throw new RuntimeException($result['error']['code'] ?? 'Veyqo request failed'); } print_r($result['data']); ``` ### Python ```python # pip install requests; run on your server. import os, requests from urllib.parse import quote response = requests.request('POST', f'https://api.veyqo.org/api/v1/payments/{quote(os.environ["PAYMENT_ID"], safe="")}/verify', headers={ "Authorization": 'Bearer ' + os.environ['VEYQO_SECRET_KEY'], "Accept": "application/json" }, timeout=30) result = response.json() if not response.ok or not result.get('success'): raise RuntimeError(f"{response.status_code} {result.get('error')} request_id={response.headers.get('X-Request-Id')}") print(result['data']) ``` ## Successful response · 200 HTTP success means the request was accepted. A pending payment or refund is not completed merely because the response is 200 or 201. ```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" } } ``` ## Response fields | Field in data | Type | Presence | Description | | --- | --- | --- | --- | | id | string | Required | Globally unique Veyqo payment ID; use it for reconciliation. | | object | "payment" | Required | See the JSON example. | | reference | string | Required | Merchant reference unique within the project environment; defaults to the payment ID. | | status | string | Required | Normalized payment state. Do not fulfil pending, processing, failed or cancelled payments. Values: created, pending, processing, succeeded, failed, cancelled, refunded, partially_refunded. | | amount | integer | Required | Original amount in the smallest currency unit. | | amount_refunded | integer | Required | Successfully refunded amount in the smallest currency unit. | | currency | string | Required | Three-letter currency code. | | customer | object | Required | See the JSON example. | | customer.email | string | Required | Customer email address. | | customer.name | string \| null | Required | Customer name. | | customer.phone | string \| null | Required | Customer phone. | | description | string \| null | Required | Optional description. | | checkout_url | string \| null | Required | Provider checkout URL for direct payments; may be null depending on the flow. Format: uri. | | provider | string | Required | Selected provider slug. | | provider_reference | string \| null | Required | Reference the provider assigned, not your order reference. | | metadata | object \| array | Required | Your non-sensitive JSON metadata. Objects are recommended; do not store secrets or card details. | | failure_code | string \| null | Required | Machine-readable payment failure reason, separate from API error codes. | | failure_message | string \| null | Required | Human-readable payment failure reason. | | authorized_at | string \| null | Required | ISO 8601 timestamp. Format: date-time. | | succeeded_at | string \| null | Required | ISO 8601 timestamp. Format: date-time. | | failed_at | string \| null | Required | ISO 8601 timestamp. Format: date-time. | | created_at | string \| null | Required | 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. | | PAYMENT_NOT_FOUND | 404 | Use the saved Veyqo payment ID or correctly URL-encoded merchant reference with the original project’s key. | 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. | | PROVIDER_UNAVAILABLE | 503 | Check the existing payment and verify its state before starting another attempt. Retry safe reads with backoff; preserve operation identity for retried writes. | Conditional: reconcile unknown outcomes first. | | PROVIDER_AUTHENTICATION_FAILED | 502 | The merchant must check/rotate the provider credentials in the dashboard. Do not expose those secrets to your application users. | After credential correction; reconcile existing payment first. | | PROVIDER_REQUEST_FAILED | 422 | Read the safe message, inspect the payment’s failure details and correct the request or provider account. Never repeatedly retry a business rejection. | Only after resolving the cause. | - [Complete error catalogue](https://veyqo.org/docs/errors): Every Veyqo error code, including which surface emits it and how to recover.