Verify Session

Verify the status of a checkout session. Use this endpoint to confirm whether a payment has been completed.

GET /v1/checkout/session/:id/verify

:id can be any of the three identifiers you might have in hand:

• the session ID returned by initialize,
• our transaction reference (ZVP-...), as sent in callbacks and webhooks, or
• your own reference from initialize (returned as merchant_reference). This is the easiest one to use, because it is the ID you already store against the order, and it is all an Inline Checkout integration receives.

Authentication

Requires an API key (public or secret).

Path parameters

Parameter	Type	Description
id	string	Session ID, our transaction reference, or your own reference

References are looked up only among your own sessions and only in the mode of the key you call with (a test key sees test sessions, a live key sees live ones). If you reused one reference for several sessions (for example re-initializing with a new amount), verify returns the completed one if there is one, otherwise the newest.

Example request

Verifying by your own reference (order_12345) works the same way: put it in place of the session ID.

cURL

curl https://api.zevpaycheckout.com/v1/checkout/session/ecc48011-e36e-4741-9b99-657f4a1ee86e/verify \
  -H "x-api-key: sk_test_your_secret_key"

Node.js

const response = await fetch(
  'https://api.zevpaycheckout.com/v1/checkout/session/ecc48011-e36e-4741-9b99-657f4a1ee86e/verify',
  {
    headers: {
      'x-api-key': 'sk_test_your_secret_key',
    },
  }
);

const { data } = await response.json();
console.log(data.status); // "completed"

Python

import requests

response = requests.get(
    "https://api.zevpaycheckout.com/v1/checkout/session/ecc48011-e36e-4741-9b99-657f4a1ee86e/verify",
    headers={"x-api-key": "sk_test_your_secret_key"},
)

data = response.json()["data"]
print(data["status"])  # "completed"

PHP

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,
  'https://api.zevpaycheckout.com/v1/checkout/session/ecc48011-e36e-4741-9b99-657f4a1ee86e/verify');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'x-api-key: sk_test_your_secret_key',
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = json_decode(curl_exec($ch), true);
$data = $response['data'];
echo $data['status']; // "completed"

Response

{
  "success": true,
  "data": {
    "session_id": "ecc48011-e36e-4741-9b99-657f4a1ee86e",
    "livemode": true,
    "reference": "ZVP-CKO-S-abc123",
    "merchant_reference": "ORDER-12345",
    "status": "completed",
    "amount": 500000,
    "currency": "NGN",
    "customer_email": "customer@example.com",
    "payment_method": "bank_transfer",
    "paid_at": "2026-03-07T19:42:00.000Z",
    "metadata": { "orderId": "12345" }
  }
}

Field	Type	Description
session_id	string	The checkout session ID
reference	string	Our transaction reference
merchant_reference	string | null	Your custom reference (if provided during initialization)
status	string	Session status (see statuses)
amount	integer	Amount in kobo
currency	string	Currency code (e.g., "NGN")
customer_email	string	Customer's email address
payment_method	string | null	Payment method used (for example "bank_transfer", "payid", "card"), or null if not yet selected
livemode	boolean	true for a live payment, false for a test payment. Fulfil only when true in production.
metadata	object | null	The metadata you sent to initialize
paid_at	string | null	ISO 8601 timestamp of when payment was confirmed, or null if not yet paid

Session statuses

Status	Description
active	Session is active, awaiting payment
completed	Payment has been received and confirmed
expired	Session expired (30-minute timeout)
failed	Payment failed

Behavior

• If the session is active but past its expires_at time, the status is automatically updated to expired before returning
• The paid_at field is only populated when status is completed
• This endpoint is idempotent; calling it multiple times returns the same result

Best Practice

Always verify payment status on your server before fulfilling orders. Do not rely solely on client-side callbacks.

Errors

Status	Message	Cause
404	Session not found.	Invalid session ID
401	Invalid API key	Key not found or inactive

Try it

API Playground

GEThttps://api.zevpaycheckout.com/v1/checkout/session/:sessionId/verify

API Key Stored locally in your browser

Path Parameters

sessionId *