Initialize Session

Create a new checkout session for collecting a payment.

POST /v1/checkout/session/initialize

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

Inline Checkout 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 and idempotency (max 255 chars). Same reference and amount returns the active session; same reference with a new amount replaces it. See idempotency
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	Methods to offer: "bank_transfer", "payid", "card", "crypto". Omit for the methods configured on your key (default ["bank_transfer", "payid"]). An explicit list is honoured exactly — include "crypto" (or pass crypto_assets) to offer it; crypto joins automatically only when payment_methods is omitted. Pass only ["crypto"] for a crypto-only checkout. See Payment Methods
crypto_assets	string[]	No	Narrow the crypto assets offered: "USDT:TRON" (one network) or "USDT" (every network). Only assets enabled on your key can appear. Omit to offer every eligible asset

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	Our 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. Includes "crypto" when the key qualifies, see Crypto
crypto_assets	array | null	Crypto assets offered on this session, each { assetCode, network, displayName, decimals }. Null when crypto is not offered

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