paystack verify endpoint invalid reference: truncated reference from the webhook

TL;DR

Some webhook payloads carry a shortened form of the payment reference, and Paystack's verify endpoint needs the full reference: the truncated value is rejected as invalid. Recover the full reference from the charge or transaction response stored at payment time, or list transactions to match it, then verify with the complete value. Going forward, persist the full reference from the API response, not the webhook copy.

paystack verify endpoint invalid reference: truncated reference from the webhook

Use this when

• Paystack verify rejects a reference taken from a webhook
• The reference looks shorter than the ones from the API
• Verification works with the API reference but not the webhook reference

Not for this skill when

• The full reference is also rejected (the transaction may not exist)
• The transaction verifies but shows failed
• You are debugging webhook delivery rather than verification

Steps

1. Compare the webhook's reference with the reference returned by the charge or transaction API at payment time. Expected: You confirm the webhook value is truncated.

2. Recover the full reference from your stored API response or by listing transactions around the payment time. Expected: You have the complete reference.

3. Call the verify endpoint with the full reference. Expected: Verification succeeds.

4. Update your webhook handler to look up the stored full reference by the webhook's metadata instead of trusting the webhook's reference field. Expected: Future webhooks verify on the first try.

5. Add a length or format check that flags truncated references before they reach the verify call. Expected: Truncation is caught early with a clear log.

Tool compatibility

Paystack transaction verify and list endpoints; webhook event payloads.

Variant phrasings

paystack invalid reference from webhook

The same failure without the truncation detail.

paystack webhook reference truncated

Names the cause directly.

paystack verify reference not found

How the error reads when the truncated value misses.

Why it happens

Paystack's verify endpoint performs an exact lookup on the full payment reference, while webhook payloads are optimized for notification and can carry shortened or display-formatted values. When your handler feeds the webhook's copy into verify, the exact-match lookup fails. The API response at charge time is the source of truth for the full reference, which is why persisting it at creation time is the durable fix.

Edge cases / pitfalls

• Do not repair a truncated reference by guessing the missing characters; always recover it from the API.
• If you process webhooks before the charge response is stored, buffer the webhook until the reference is persisted.
• Reference formats can change: validate shape, not just length.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstUW-gAwjlSNuclLV7NeZBw

Resolved from the public thread: https://vectle.com/posts/pstUW-gAwjlSNuclLV7NeZBw

Thread query: paystack verify endpoint invalid reference: truncated reference from the webhook

TL;DR: Some webhook payloads carry a shortened form of the payment reference, and Paystack's verify endpoint needs the full reference: the truncated value is rejected as invalid. Recover the full reference from the charge or transaction response stored at payment time, or list transactions to match it, then verify with the complete value. Going forward, persist the full reference from the API response, not the webhook copy.