Shipmind Labs

A refund came back to us verified, signed correctly, and belonging to a different transaction.

Nothing in our code noticed.

The flow was ordinary. We sign a refund request, post it to the payment gateway, get a document back, check the signature, and if the signature holds we treat the answer as the answer. That last step is the bug. It reads as common sense right up until the day a response arrives that is cryptographically perfect and about someone else's money.

Signature verification tells you who spoke. It tells you nothing about what they replied to.

So in bluemedia, our open-source gateway client, we made the identifier a first-class check instead of something we assume. The exchange step now carries the message id of the request we actually signed, and once verification succeeds it compares that id against the one on the answer. Refund and cancel both pass the id from the request object they signed, so there is no second source of truth to drift. Start does the same thing with the order id: parse the body, decide whether it is a refusal or a transaction init, verify the document, then match the order id against the one we sent.

Three details turned out to matter more than the check itself.

Order of checks. Verification runs first. An answer signed with the wrong key is a verification error even when the identifier is also wrong, because we do not want a mismatch message describing a document we have no reason to trust. And a refusal that belongs to another order raises a mismatch, not a refusal, since acting on someone else's refusal is worse than not acting at all.

The error carries evidence. Field, expected, found, and the full response, with both identifiers named in the message. Whoever reads that log at an awkward hour should not have to reconstruct what we compared.

The match does not respect the verify-responses switch. Teams turn verification off in sandboxes and local runs, and that is a reasonable thing to want. Accepting an answer for a different request is not a reasonable thing to want, so a client built with verification disabled still refuses it.

We also left one path alone. Status returns a list of notifications, each verified on its own, so a single top-level identifier would be the wrong shape for it. Resisting the urge to apply the rule uniformly was part of getting it right.

The general version, for anyone building against a payment or compliance API: separate the question "is this authentic" from the question "is this mine". Most clients we inherit answer the first and quietly assume the second.

If you run money flows, it is worth saying out loud where your correlation check sits, in the transport layer or in the business logic.

Was this useful?

Building something similar?

or email hello@shipmindlabs.com