API Reference PaymentsCreate Payment Session

Create Payment Session

POST/v1/payments/sessionsCore

Create a hosted-checkout session. The session holds the amount, description, and redirect URLs; the buyer completes the card (or TR QR) flow on the Kvell hosted page. Set mode="qr" to mint a BKM/TCMB TR QR payment instead of a card checkout.

Authentication

Signature Pattern

HMAC-SHA256(secretKey, "{timestamp}\nPOST\n/v1/payments/sessions\n{sha256(body)}")

Header	Value	Description
`X-Api-Key`	pk_live_a1b2c3d4e5f6g7h8	Merchant public API key
`X-Signature`	{hmac_sha256_hex}	Hex HMAC-SHA256 request signature (see below)
`X-Timestamp`	2026-04-13T10:00:00Z	ISO 8601 UTC request time, validated within ±5 min

Request Parameters

Name	Type	Required	Description
`transactionId`	string	Required	Unique merchant transaction id (idempotency fence, unique per merchant)
`amount`	integer	Optional	Amount in kuruş (1/100 TRY). >=100 for mode="payment"/"qr"; omit for mode="card_update_only"
`currency`	string	Required	ISO 4217, always "TRY" in Phase 1
`description`	string	Optional	Transaction description shown on the checkout page
`returnUrl`	string	Required	Redirect URL after the buyer finishes (success or failure)
`callbackUrl`	string	Optional	Override the store default webhook URL for this payment
`installmentEnabled`	boolean	Optional	Show the installment picker on the hosted page
`customerId`	string	Optional	Bind the session to a saved customer (enables save-card)
`mode`	string	Optional	"payment" (default) \| "card_update_only" \| "qr"
`splits`	array	Optional	Marketplace split config [{submerchantId, amountMinor}] — payment mode only

Request Example

JSONRequest Body

{
  "transactionId": "ORDER-2026-001",
  "amount": 15000,
  "currency": "TRY",
  "description": "Order #1234",
  "returnUrl": "https://merchant.example.com/return"
}

Response Parameters

Field	Type	Example
`sessionId`	string	"3f1c9a2e-6b4d-4e8a-9c1f-2a7b8c9d0e1f"
`checkoutUrl`	string	"https://pay.kvell.group/s/3f1c9a2e-6b4d-…
`expiresAt`	string	"2026-04-13T10:30:00Z"
`merchantId`	string	"mrc_8a1b2c3d4e5f"
`amount`	integer	15000
`currency`	string	"TRY"
`status`	string	"active"

Response Example

JSONResponse

{
  "sessionId": "3f1c9a2e-6b4d-4e8a-9c1f-2a7b8c9d0e1f",
  "checkoutUrl": "https://pay.kvell.group/s/3f1c9a2e-6b4d-4e8a-9c1f-2a7b8c9d0e1f",
  "expiresAt": "2026-04-13T10:30:00Z",
  "merchantId": "mrc_8a1b2c3d4e5f",
  "amount": 15000,
  "currency": "TRY",
  "status": "active"
}

Status Codes

200Success

201Created

400Bad Request

401Unauthorized

404Not Found

429Rate Limited

Try itMock

POSThttps://api.pay.sandbox.kvell.group

Charge Tokenized Card→