Create Payment

Creates an invoice, a payment record, initiates the Smart Contract payout, and returns a hosted payment URL for the payer. This is the primary server-to-server operation documented in this guide.

Endpoint

Property	Value
Method	POST
Path	/sdk/server/create-payment
Content-Type	application/json

Full URL: <Sandbox-environment>/sdk/server/create-payment (see Base URL & environments).

Authentication & policy

This endpoint requires all of the following:

• Valid API key and secret (see Authentication).

• Valid HMAC signature headers (see Request signing).

• X-Idempotency-Key (see Idempotency).

Middleware order on the server: invalid-auth rate limit → merchant authentication → per-key rate limit → signature verification → idempotency → controller.

Request headers

Header	Required	Description
Authorization or X-API-Key	Yes	API key (Bearer <apiKey> or raw header).
X-Secret-Key	Yes	Secret paired with the API key.
X-API-Key	Yes	Must match the authenticated API key; required for signing (avoids ambiguity with Authorization).
X-Timestamp	Yes	Unix time in seconds (digits only).
X-Signature	Yes	HMAC-SHA256 hex digest of the signature base.
X-Idempotency-Key	Yes	Opaque unique key per logical operation.
Content-Type	Yes	application/json

Request body

Top-level fields

Field	Type	Required	Description
source	string	Yes	Label or origin for this invoice (e.g. storefront or product name).
clientEmail	string	Yes	Valid email; used for payer-facing communications.
clientName	string	Yes	Display name for the payer.
clientWalletAddress	string	Yes	Ethereum address: 0x followed by 40 hexadecimal characters.
countryCode	string	Yes	Country code for your integration.
countryName	string	Yes	Country name.
invoiceCurrency	string	Yes	Must be one of the allowed values (see below).
paymentCurrency	string	Yes	Same allowed set as invoiceCurrency.
items	array	Yes	At least one line item (see Line items).
isSelfIncurredFee	boolean	Yes	If true, fee semantics follow self-incurred configuration in Kollect.
dueDate	string	No	Defaults to today’s date (YYYY-MM-DD) if omitted.
invoiceNumber	string	No	Defaults to INV-<timestamp>. Must be unique per merchant; duplicates return 409.
notes	string	No	Defaults to empty string.
interface	string	No	One of kollect-app, kollect-sdk, kollect-server. Defaults to kollect-server. Use kollect-server for merchant webhooks.

Allowed currency values

invoiceCurrency and paymentCurrency must each be one of:

• USDC-mainnet

• USDT-mainnet

• USDT-matic

• USDCn-matic

• fUSDC-sepolia

• fUSDT-sepolia

Line items

Each element of items must include:

Field	Type	Constraints
description	string	Required.
quantity	number	Required; minimum 1.
price	number	Required.

Invoice amount is computed server-side as the sum of price × quantity across items.

Success response

HTTP status: 200

{
  "status": true,
  "data": {
    "paymentUrl": "https://<FRONTEND_URL>/kollect/payment/<paymentId>",
    "paymentId": "550e8400-e29b-41d4-a716-446655440000",
    "invoiceId": "64a1b2c3d4e5f6789012345",
    "invoiceNumber": "INV-1001"
  }
}

Field	Description
paymentUrl	Hosted checkout URL. Built from the deployment’s FRONTEND_URL and the payment UUID.
paymentId	UUID for the payment record (id field).
invoiceId	Invoice document identifier (MongoDB _id).
invoiceNumber	Human-readable invoice number stored on the invoice.

Error responses

Errors use the standard Kollect error envelope.

Example request body

{
  "source": "my-store-checkout",
  "clientEmail": "[email protected]",
  "clientName": "Jane Buyer",
  "clientWalletAddress": "0x0000000000000000000000000000000000000001",
  "countryCode": "US",
  "countryName": "United States",
  "invoiceCurrency": "USDC-mainnet",
  "paymentCurrency": "USDC-mainnet",
  "isSelfIncurredFee": false,
  "dueDate": "2025-03-23",
  "invoiceNumber": "INV-1001",
  "notes": "Order #1001",
  "items": [
    {
      "description": "Premium plan — 1 month",
      "quantity": 1,
      "price": 49.99
    }
  ]
}

cURL example

API_KEY="your_api_key"
SECRET="your_secret_key"
BODY='{"source":"my-app","clientEmail":"[email protected]","clientName":"A","clientWalletAddress":"0x1111111111111111111111111111111111111111","countryCode":"US","countryName":"United States","invoiceCurrency":"fUSDC-sepolia","paymentCurrency":"fUSDC-sepolia","isSelfIncurredFee":false,"items":[{"description":"Item","quantity":1,"price":10}]}'
TS=$(date +%s)
PATH_ONLY="/sdk/server/create-payment"
BODY_HASH=$(printf '%s' "$BODY" | shasum -a 256 | awk '{print $1}')
BASE="POST
${PATH_ONLY}
${TS}
${BODY_HASH}"
SIG=$(printf '%s' "$BASE" | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.* //')
IDEM=$(uuidgen)

curl -sS -X POST "https://<host>${PATH_ONLY}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "X-Secret-Key: ${SECRET}" \
  -H "X-API-Key: ${API_KEY}" \
  -H "X-Timestamp: ${TS}" \
  -H "X-Signature: ${SIG}" \
  -H "X-Idempotency-Key: ${IDEM}" \
  -d "$BODY"

Adjust openssl output parsing if your platform prints a different digest line format; the signature must be lowercase hex matching the server implementation.

Related pages

• Authentication

• Request signing

• Rate limits

• Payment lifecycle