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 expires 30 minutes after creation and accepts one payment. 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.
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,
"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-27T14:02: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.
ISO-8601 timestamp, 30 minutes after creation.
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, 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 |
