> For the complete documentation index, see [llms.txt](https://kreatorverse-2.gitbook.io/kollect-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kreatorverse-2.gitbook.io/kollect-documentation/api-reference/create-payment.md).

# 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 <a href="#endpoint" id="endpoint"></a>

| 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](/kollect-documentation/api-reference.md)).

### Authentication & policy <a href="#authentication-and-policy" id="authentication-and-policy"></a>

This endpoint requires **all** of the following:

* Valid **API key** and **secret** (see [Authentication](/kollect-documentation/security.md)).
* Valid **HMAC signature** headers (see [Request signing](/kollect-documentation/security/request-signing.md)).
* **`X-Idempotency-Key`** (see [Idempotency](/kollect-documentation/security/idempotency.md)).

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

### Request headers <a href="#request-headers" id="request-headers"></a>

| 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](/kollect-documentation/security/request-signing.md).     |
| `X-Idempotency-Key`                | Yes      | Opaque unique key per logical operation.                                                                |
| `Content-Type`                     | Yes      | `application/json`                                                                                      |

### Request body <a href="#request-body" id="request-body"></a>

#### Top-level fields <a href="#top-level-fields" id="top-level-fields"></a>

| 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](https://app.gitbook.com/o/UUVwop2y3em3cccnVwco/s/XJMxY58UtnAyDJp9oo8I/api-reference/create-payment#line-items)).   |
| `isSelfIncurredFee`   | boolean | No       | Send `true` to apply self-incurred fee semantics. **Anything other than a literal `true`/`"true"` — including omitting the field — is treated as `false`.** |
| `dueDate`             | string  | No       | Defaults to **today’s date** (`YYYY-MM-DD`) if omitted. Not format-validated server-side — send `YYYY-MM-DD` regardless.                                    |
| `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`.**                                                                    |

{% hint style="warning" %}
**Only `kollect-server` payments trigger your outbound webhook.** If you explicitly pass `interface: "kollect-app"` or `"kollect-sdk"`, the payment is created normally but Kollect will **never** call your `webhookUrl` for it — the outbound-webhook service is gated on `payment.interface === "kollect-server"`. Omit `interface` (letting it default) unless you have a specific reason to override it.
{% endhint %}

### 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`

```json
{
  "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](/kollect-documentation/reference/error-handling.md).

## Example request body

```json
{
  "source": "my-store-checkout",
  "clientEmail": "buyer@example.com",
  "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

```bash
API_KEY="your_api_key"
SECRET="your_secret_key"
BODY='{"source":"my-app","clientEmail":"a@b.com","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](/kollect-documentation/security.md)
* [Request signing](/kollect-documentation/security/request-signing.md)
* [Rate limits](/kollect-documentation/reference/rate-limits.md)
* [Payment lifecycle](/kollect-documentation/introduction/architecture-and-data-flow.md)