Create Invoice

POST/v1/invoicesOptional

Create a draft invoice. lineItems must sum to amountMinor. Accepts an optional Idempotency-Key header.

Authentication

Signature Pattern

HMAC-SHA256(secretKey, "{timestamp}\nPOST\n/v1/invoices\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
`X-Timestamp`	2026-04-13T10:00:00Z	ISO 8601 UTC request time (±5 min)

Request Parameters

Name	Type	Required	Description
`storeId`	string	Required	Store the invoice belongs to
`customerId`	string	Optional	Bind the invoice to a customer
`amountMinor`	integer	Required	Total in kuruş (must equal sum of lineItems)
`currency`	string	Required	Always "TRY"
`lineItems`	array	Required	[{name, qty, unitPriceMinor, lineTotalMinor}]
`buyerEmail`	string	Optional	Required before /send (email delivery)
`buyerName`	string	Optional	Buyer display name
`dueDate`	string	Optional	ISO 8601 due date
`expiresAt`	string	Optional	ISO 8601 link expiry
`notes`	string	Optional	Free-text note on the invoice

Request Example

JSONRequest Body

{
  "storeId": "sto_5a6b7c8d",
  "amountMinor": 50000,
  "currency": "TRY",
  "lineItems": [
    {
      "name": "Monthly subscription",
      "qty": 1,
      "unitPriceMinor": 50000,
      "lineTotalMinor": 50000
    }
  ],
  "buyerEmail": "buyer@example.com",
  "dueDate": "2026-04-20T12:00:00Z"
}

Response Parameters

Field	Type	Example
`id`	string	"inv_7a8b9c0d1e2f"
`merchantId`	string	"mrc_8a1b2c3d4e5f"
`storeId`	string	"sto_5a6b7c8d"
`publicHash`	string	"aB3xK9mN2pQ7rS1tV5wY8z"
`status`	string	"draft"
`amountMinor`	integer	50000
`currency`	string	"TRY"
`lineItems`	array	[…]
`lineItems[].name`	string	"Monthly subscription"
`lineItems[].qty`	integer	1
`lineItems[].unitPriceMinor`	integer	50000
`lineItems[].lineTotalMinor`	integer	50000
`buyerEmail`	string	"buyer@example.com"
`url`	string	"https://pay.kvell.group/invoice/aB3xK9mN…
`createdAt`	string	"2026-04-13T10:00:00Z"

Response Example

JSONResponse

{
  "id": "inv_7a8b9c0d1e2f",
  "merchantId": "mrc_8a1b2c3d4e5f",
  "storeId": "sto_5a6b7c8d",
  "publicHash": "aB3xK9mN2pQ7rS1tV5wY8z",
  "status": "draft",
  "amountMinor": 50000,
  "currency": "TRY",
  "lineItems": [
    {
      "name": "Monthly subscription",
      "qty": 1,
      "unitPriceMinor": 50000,
      "lineTotalMinor": 50000
    }
  ],
  "buyerEmail": "buyer@example.com",
  "url": "https://pay.kvell.group/invoice/aB3xK9mN2pQ7rS1tV5wY8z",
  "createdAt": "2026-04-13T10:00:00Z"
}

Status Codes

200Success

201Created

400Bad Request

401Unauthorized

404Not Found

429Rate Limited

Try itMock

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

List Invoices→