# Verify Session

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

```
GET /v1/checkout/session/:sessionId/verify
```

**Required permission:** `checkout`

## Authentication

Requires an API key (public or secret).

## Path parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `sessionId` | string | The checkout session ID |

## Example request

::: code-group

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

```js [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 [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 [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

```json
{
  "success": true,
  "data": {
    "session_id": "ecc48011-e36e-4741-9b99-657f4a1ee86e",
    "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"
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `session_id` | string | The checkout session ID |
| `reference` | string | ZevPay transaction reference |
| `merchant_reference` | string \| null | Your custom reference (if provided during initialization) |
| `status` | string | Session status — see [statuses](#session-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 (`"bank_transfer"` or `"payid"`), or `null` if not yet selected |
| `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

::: tip 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

<ApiPlayground
  method="GET"
  endpoint="/v1/checkout/session/:sessionId/verify"
  :pathParams="[
    { name: 'sessionId', type: 'string', required: true, placeholder: 'ecc48011-e36e-4741-9b99-657f4a1ee86e' },
  ]"
/>