# Initialize Session Create a new checkout session for collecting a payment. ``` POST /v1/checkout/session/initialize ``` **Required permission:** `checkout` ## Authentication This endpoint accepts both **secret keys** (`sk_*`) and **public keys** (`pk_*`). | Key type | Use case | Origin validation | |----------|----------|-------------------| | **Secret key** | Server-to-server (standard checkout, API-only) | None | | **Public key** | Client-side (inline checkout SDK) | Enforced if `allowedDomains` is configured on the key | ::: tip Inline checkout — no backend required The [Inline Checkout SDK](/sdks/inline) uses your public key to call this endpoint directly from the browser. You don't need a backend server to accept payments with inline checkout. Configure `allowedDomains` on your API key to restrict which domains can use it. See [Domain Whitelisting](/guide/authentication#domain-whitelisting). ::: ## Request body | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `amount` | integer | Yes | Amount in **kobo** (minor units). Minimum: `100` (NGN 1.00) | | `email` | string | Yes | Customer's email address | | `customer_name` | string | No | Customer's name (max 255 chars). Displayed in dashboard instead of "Anonymous" | | `currency` | string | No | Currency code (max 3 chars). Default: `"NGN"` | | `reference` | string | No | Your unique reference for reconciliation (max 255 chars) | | `callback_url` | string | No | URL to redirect after payment — required for standard checkout (max 2048 chars) | | `metadata` | object | No | Custom key-value data stored with the session | | `payment_methods` | string[] | No | Enabled methods: `"bank_transfer"`, `"payid"`. Default: `["bank_transfer", "payid"]` | ## Example request ::: code-group ```bash [cURL] curl -X POST https://api.zevpaycheckout.com/v1/checkout/session/initialize \ -H "Content-Type: application/json" \ -H "x-api-key: sk_test_your_secret_key" \ -d '{ "amount": 500000, "email": "customer@example.com", "customer_name": "John Doe", "currency": "NGN", "reference": "ORDER-12345", "callback_url": "https://yoursite.com/callback", "metadata": { "order_id": "12345" }, "payment_methods": ["bank_transfer", "payid"] }' ``` ```javascript [Node.js] const response = await fetch( "https://api.zevpaycheckout.com/v1/checkout/session/initialize", { method: "POST", headers: { "Content-Type": "application/json", "x-api-key": "sk_test_your_secret_key", }, body: JSON.stringify({ amount: 500000, email: "customer@example.com", customer_name: "John Doe", currency: "NGN", reference: "ORDER-12345", callback_url: "https://yoursite.com/callback", }), } ); const { data } = await response.json(); console.log(data.session_id); // "ecc48011-e36e-4741-9b99-657f4a1ee86e" console.log(data.checkout_url); // "https://secure.zevpaycheckout.com/ecc48011-..." ``` ```python [Python] import requests response = requests.post( "https://api.zevpaycheckout.com/v1/checkout/session/initialize", headers={ "Content-Type": "application/json", "x-api-key": "sk_test_your_secret_key", }, json={ "amount": 500000, "email": "customer@example.com", "customer_name": "John Doe", "currency": "NGN", "reference": "ORDER-12345", "callback_url": "https://yoursite.com/callback", }, ) data = response.json()["data"] print(data["session_id"]) print(data["checkout_url"]) ``` ```php [PHP] $ch = curl_init("https://api.zevpaycheckout.com/v1/checkout/session/initialize"); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_HTTPHEADER => [ "Content-Type: application/json", "x-api-key: sk_test_your_secret_key", ], CURLOPT_POSTFIELDS => json_encode([ "amount" => 500000, "email" => "customer@example.com", "customer_name" => "John Doe", "currency" => "NGN", "reference" => "ORDER-12345", ]), ]); $response = json_decode(curl_exec($ch), true); $sessionId = $response["data"]["session_id"]; ``` ::: ## Response ```json { "success": true, "data": { "session_id": "ecc48011-e36e-4741-9b99-657f4a1ee86e", "reference": "ZVP-CKO-S-1772906868046-d5aa1c0b99153aae4766af242e656e80", "merchant_reference": "ORDER-12345", "checkout_url": "https://secure.zevpaycheckout.com/ecc48011-e36e-4741-9b99-657f4a1ee86e", "amount": 500000, "currency": "NGN", "expires_at": "2026-03-07T19:37:00.000Z", "merchant_name": "Your Business Name", "enabled_payment_methods": ["bank_transfer", "payid"] } } ``` ### Response fields | Field | Type | Description | |-------|------|-------------| | `session_id` | string | Unique session identifier (UUID) | | `reference` | string | ZevPay's unique payment reference (prefix: `ZVP-CKO-S`) | | `merchant_reference` | string \| null | Your reference (if provided) | | `checkout_url` | string | URL for standard checkout redirect | | `amount` | integer | Amount in kobo (same as request) | | `currency` | string | Currency code | | `expires_at` | string | ISO 8601 expiry timestamp (30 minutes from creation) | | `merchant_name` | string \| null | Your business name from checkout configuration | | `enabled_payment_methods` | string[] | Active payment methods for this session | ## Errors | Status | Message | Cause | |--------|---------|-------| | `400` | Validation error | Missing or invalid parameters (e.g., `amount must not be less than 100`) | | `401` | Invalid API key | Key not found or inactive | | `403` | Origin not allowed for this API key | Public key used from unauthorized domain | ## Try it