Create a collection
Creates a single-use deposit address and a hosted payment link for one payment. When the deposit is confirmed on-chain, the proceeds are credited to your API account.
A collection address accepts one payment and expires after 30 minutes by
default. Set expiry at creation to choose 5–60 minutes, in seconds. Create it when your customer is ready to pay, not when the invoice is
drafted — and create a fresh one if the window lapses.
Body
The chain the payment will arrive on. Must be a network whose
collectionStatus is ACTIVE in
GET /api/v1/networks.
The token being collected, for example USDT or USDC. Must be active for
collections on the chosen network.
The amount to collect, in token units. Must be greater than zero.
Payment window in whole seconds. Minimum 300 (5 minutes), maximum 3600
(60 minutes), inclusive. Omit this field to keep the 30-minute default;
900 gives the customer 15 minutes. Do not send minutes or a timestamp.
Explicit null, fractional values, and values outside the range are invalid.
How many on-chain confirmations to wait for before the collection is treated as confirmed. Must be greater than zero. Higher values trade settlement speed for finality — pick a value appropriate to the network and the size of the payment.
Where this collection's webhooks are delivered. Must be a publicly
reachable http:// or https:// URL — private, loopback, and internal
addresses are rejected.
Where the hosted payment page sends the customer after payment. Must be a
valid http:// or https:// URL if supplied.
merchantCallbackUrl is a delivery target, not a label. Collection webhooks
go to this URL; only if it is somehow absent do they fall back to the webhook
URL configured on your business.
Request
curl -X POST "https://api-prod.useknit.io/api/v1/collections" \
-H "Authorization: Bearer $KNIT_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"network": "MATIC_MAINNET",
"token": "USDT",
"tokenAmount": 2500,
"expiry": 900,
"confirmationThreshold": 10,
"merchantCallbackUrl": "https://example.com/webhooks/knit",
"merchantRedirectUrl": "https://example.com/thanks"
}'Response
Returns 200 with the created collection.
{
"statusCode": 200,
"message": "Collection created successfully",
"data": {
"id": "9cddd3ad-c2a8-463c-a703-158b900beea8",
"network": "MATIC_MAINNET",
"token": "USDT",
"address": "0x3761f3504104f4faa8959963a5d8dce89989d45b",
"status": "PENDING",
"tokenAmountRequested": 2500,
"tokenAmount": 2500,
"tokenToUsd": 1,
"feeInUsd": 0,
"feeByToken": 0,
"confirmationThreshold": 10,
"merchantCallbackUrl": "https://example.com/webhooks/knit",
"merchantRedirectUrl": "https://example.com/thanks",
"paymentLinkUrl": "https://checkout.collection.useknit.io/9cddd3ad-c2a8-463c-a703-158b900beea8",
"expiresAt": "2024-08-27T13:47:10.000000Z",
"createdAt": "2024-08-27T13:32:10.000000Z",
"updatedAt": "2024-08-27T13:32:10.000000Z"
},
"success": true
}The single-use deposit address. Show it to the customer, or embed it in a QR code.
A hosted checkout page for this collection. The simplest integration is to redirect the customer here.
The payment deadline as an ISO-8601 timestamp. Knit uses the same deadline for the deposit address and this response. Base your countdown on this value rather than starting a new timer when the response arrives.
Starts at PENDING. See the lifecycle below.
Lifecycle
| Status | Meaning |
|---|---|
PENDING | Address issued, waiting for a deposit |
SUCCESSFUL | Deposit received and credited to your API account |
SUCCESSFUL_PARTIAL | Less than the requested amount arrived; the received amount was credited |
FAILED | The payment could not be completed |
Each transition emits a webhook:
COLLECTION_CREATED— fired immediately on creation.COLLECTION_CONFIRMED— fired once yourconfirmationThresholdis reached.COLLECTION_SUCCESSFUL— fired when the funds are credited.COLLECTION_FAILED— fired if the payment cannot be completed.
See Webhooks for payloads and signature verification.
Errors
| Status | Cause |
|---|---|
401 | Missing or invalid token, IP not allow-listed, or missing collections:write |
400 | A required field is missing, expiry is not an integer from 300 to 3600, tokenAmount or confirmationThreshold is not greater than zero, or a URL is invalid or not publicly reachable |
500 | The collection could not be created. Retry; if it persists, contact support |
