COLLECTION_SUCCESSFUL
Delivered when a collection's funds have been credited to your API account. This is the event to act on: the money is yours and available to pay out.
Delivered to the collection's merchantCallbackUrl, falling back to your
business webhook URL.
Payload
COLLECTION_SUCCESSFUL
{
"body": {
"eventType": "COLLECTION_SUCCESSFUL",
"collection": {
"id": "4ebdfe45-a62b-47a9-ac31-7599305666b1",
"business_id": "b7b93a40-4e18-4e97-9c5f-8a7a4fd0df92",
"network": "MATIC_MAINNET",
"token": "USDT",
"address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
"token_amount": "25.000000000000000000",
"token_amount_requested": "25.000000000000000000",
"token_amount_received": "25.000000000000000000",
"token_to_usd": "1.00000000",
"fee_in_usd": "0.00000000",
"status": "SUCCESSFUL",
"transaction_hash": "0xb480ed44a275f042e482a78d9c5b54fcf612441c",
"transaction_block_number": 61234567,
"number_of_confirmations": 12,
"confirmation_threshold": 10,
"merchant_redirect_url": "https://example.com/thanks",
"merchant_callback_url": "https://example.com/webhooks/knit",
"expires_at": "2024-02-22T17:29:33.000000Z",
"created_at": "2024-02-22T16:59:33.000000Z",
"updated_at": "2024-02-22T17:00:30.000000Z"
}
}
}Partial payments
status is SUCCESSFUL_PARTIAL when less than the requested amount arrived.
The received amount is still credited, so treat this event as money-in — but
reconcile the shortfall.
Distinguishing full from partial
const c = payload.collection;
const paidInFull = c.status === "SUCCESSFUL";
const shortfall =
Number(c.token_amount_requested) - Number(c.token_amount_received ?? 0);⚠️
Always credit your customer against token_amount_received, never against
token_amount_requested. Amounts are decimal strings — parse them with a
decimal library rather than a float.
Handling
- Verify the signature and return
2xxpromptly. - Look the collection up by
idon your side and check you have not already processed it — this event can arrive more than once. - Credit against
token_amount_received. - Fulfil the order.
See also
COLLECTION_FAILED- Retrieve a collection — to reconcile
- Webhooks overview — signature verification and retries
