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

Inline checkout — no backend required

The Inline Checkout SDK 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.

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

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"]
  }'

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

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

$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

{
  "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

API Playground

POSThttps://api.zevpaycheckout.com/v1/checkout/session/initialize

API Key Stored locally in your browser

Request Body

amount *integer

email *string

customer_name string

currency string

reference string

callback_url string

metadata object

payment_methods array