Back to the blogEngineering

Three webhooks are the whole integration

Pincode EngineeringSep 18, 20266 min read

Most payment integrations ask you to model a dozen states and reconcile edge cases forever. We collapsed the merchant surface to three events that matter: payment.held, payment.released, payment.refunded.

On payment.held, the buyer’s money is secured at the partner bank — this is your green light to fulfil the order, guaranteed. On payment.released, the funds are yours and the payout settles. On payment.refunded, the buyer got their money back and you owe nothing.

Every webhook is HMAC-signed and de-duplicated by id, retried with backoff. You verify the signature in constant time, reject anything unsigned, and treat the event as idempotent. That’s the contract.

The golden rule we tell every integrator: fulfil on held, recognise revenue on released, and never fulfil on awaiting_funding. Get those three right and the hard parts — disputes, reversals, reconciliation — stop being your problem.