References
The format rules every reference field on BEEM must follow.
Every payment object on BEEM — Payment Links, Channels, and the channel deposits that flow through them — carries a reference field that you set. References are your internal identifier for the transaction and travel with the payment through every status change, webhook, and reconciliation export. The same format rules apply wherever a reference is accepted.
Format rules
| Rule | Requirement |
|---|---|
| Length | Minimum 6 characters |
| Allowed characters | Letters (a–z, A–Z), numbers (0–9), hyphens (-), underscores (_), and dots (.) |
| Spaces | Not allowed anywhere |
| Uniqueness | Must be unique across your account — the same reference cannot be reused on another transaction |
The regex equivalent of the character and length rules:
^[a-zA-Z0-9._-]{6,}$Valid and invalid examples
| Reference | Status | Reason |
|---|---|---|
PAY-001 | ✅ Valid | Meets all requirements |
inv.2024_06 | ✅ Valid | Meets all requirements |
ORDER.001.A | ✅ Valid | Meets all requirements |
abc | ❌ Invalid | Too short — under 6 characters |
PAY 001 | ❌ Invalid | Contains a space |
ref#99! | ❌ Invalid | Contains disallowed characters (#, !) |
PAY-001 (reused) | ❌ Invalid | Reference already used in a previous transaction |
Choosing a good referencePick something stable and meaningful from your own system — an order ID, invoice number, or internal payment UUID. References are visible in the Portal, returned on API responses, and included in every webhook for the payment, so a structured, recognisable format saves time during reconciliation and support.
Where references appear
The same format applies wherever a reference is accepted or returned, including:
- Payment Links — set at create time on
POST /api/v1/pay/summary, returned on every status change. - Channels — set at create time on
POST /api/v2/channel, attached to every channel deposit. - Channel Payments — inherits the parent Channel's reference.
- Webhooks — included in the payload of every event for the payment.
- Exports — appears as the
Merchant Referencecolumn on transaction CSVs.