Transaction References: Identity and Idempotency Guide

References uniquely identify every Paylink transaction. Learn how to generate, store, and use them to track payments and prevent duplicates.

Every transaction on Paylink — payments, virtual accounts, direct debits, refunds, and transfers — is identified by an opaque string reference. References are the primary key you use to look up transaction status, reconcile records, and correlate webhook events back to your own database. Treat them as durable identifiers and persist them as soon as you create a transaction.

What Is a Reference?

A reference is a unique string that you supply when you initialise a transaction, or that Paylink generates for you when you do not provide one. References are:

• Opaque — Paylink treats them as arbitrary strings. You can encode any identifier format that is meaningful to your system.
• Unique per operation — Each payment, virtual account, direct debit, refund, or transfer must have a distinct reference. Reusing a reference across different transaction types or across transactions in the same category is not allowed.
• Immutable — Once a reference is associated with a transaction, it cannot be changed.

How to Use References

1. Pass your reference at initialisation

   Supply your reference in the request body when you call an initialisation endpoint such as /payments/initialize. If you omit it, the API generates one for you — but you should always provide your own so that you control the value and can tie it to your internal records.

   {
     "reference": "order_12345",
     "amount": 2500,
     "currency": "NGN"
   }
   
2. Persist the reference immediately

   Store the reference in your database before you redirect the customer or trigger any downstream action. If a network failure interrupts the response, you can use the stored reference to query the transaction status rather than creating a duplicate.

3. Use the reference for status queries

   Pass the reference as a path or query parameter to verification and lookup endpoints (for example, /payments/verify/{reference}) to retrieve the current status of any transaction.

4. Correlate incoming webhook events

   Webhook payloads include a reference (and sometimes a payment_reference) field in the data object. Match this value against your stored references to identify which transaction the event relates to.

Best Practices

• Generate a unique reference for every transaction. A UUID v4 or a combination of your internal order ID and a timestamp both work well.
• Store the reference before calling the API. Write it to your database first so you can recover from partial failures.
• Never reuse a reference. Even if an earlier transaction using that reference failed, submitting it again will be rejected.
• Do not parse or construct meaning from references returned by the API. Their format may change; rely only on the value itself.

Reference Errors

When something goes wrong with a reference, the API returns a descriptive error. The table below lists every reference-related error, what causes it, and how to recover.

HTTP Status	Error Message	Cause	How to Handle
404	Invalid transaction reference	The reference string is malformed or does not match any known transaction	Verify that you are sending the correct reference and that it belongs to the right environment (sandbox vs. live)
404	Transaction record not found	The reference is well-formed but no transaction exists for it	Check that the transaction was successfully created; if you are in the wrong environment, switch and retry
409	Reference already exists	You supplied a reference that is already associated with a different transaction	Generate a new, unique reference and retry the request
409	Duplicate transaction reference	You submitted the same reference for a transaction that is already in progress or completed	Do not retry with the same reference; query the existing transaction using the reference to get its current status
410	Transaction reference has expired	The transaction was created but was not completed within the allowed time window	Create a new transaction with a new reference