Architecture and data flow

This page explains how the merchant backend, Kollect API, Smart Contract, and your Webhook endpoint interact during a payment.

---

System context

Key idea: You implement two integration surfaces:

1. Outbound from you: authenticated calls to Kollect to create payments.

2. Inbound to you: HTTP POST from Kollect to your registered webhookUrl (optional but recommended for automation).

---

Sequence diagram

---

Component responsibilities

Component	Responsibility
Merchant backend	Holds API key and secret; signs requests; stores idempotency keys; enqueues fulfillment on webhook.
Kollect API	Authenticates S2S requests; creates invoice and payment records; initiates Smart Contract payout; sends payer communications as implemented.
Smart Contract	Settles the on-chain payment and notifies Kollect.
Kollect SC webhook receiver	Validates X-Smart-Contract-Signature, maps events to internal payments, updates database.
Merchant webhook	Verifies X-Kollect-Signature, returns 2xx quickly, updates your order or billing system.

---

Integration surfaces (interface)

Payments created via POST /sdk/server/create-payment default to interface: kollect-server. Outbound webhooks to your server are only sent when this integration type applies and your webhook is registered and active.

---

Related pages

• Getting started

• Create payment URL

• Webhooks overview