Skip to main content
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.
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.