orderId / reference: transaction identification strategy
Every payment processed through Vipps MobilePay is tagged with a transaction identifier — called orderId or reference depending on the API. How you design these identifiers has a direct impact on your ability to reconcile payments, resolve disputes, and scale your operations.
This page explains the business value of a thoughtful identification strategy and the practical rules your team needs to implement it.
Why this matters​
A well-designed transaction ID is more than a technical requirement — it is the foundation of your payment operations:
-
Faster dispute resolution. When a customer contacts support or initiates a chargeback, a unique, descriptive transaction ID allows your team (and ours) to pinpoint the payment instantly. Poor IDs — such as short numeric strings like
12345— are ambiguous and can turn a five-minute lookup into a costly investigation. -
Clean financial reconciliation. Your accounting systems, ERP, and payment reports all rely on transaction IDs to match payments to orders. Collisions or ambiguous IDs create reconciliation errors that cost time and introduce financial risk.
-
Operational visibility across channels. If you operate multiple stores or sales units, embedding a store or unit prefix in the ID gives you instant, queryable business intelligence — you can filter all transactions for a specific store directly from reports without any additional data mapping.
-
Better checkout experience. The transaction ID is displayed to the end user in the Vipps or MobilePay app. A readable, recognizable reference (e.g.,
acme-shop-order-1042) builds trust and helps customers confirm they are paying the right merchant for the right purchase. -
System performance. Very short IDs (a few digits only) create lookup overhead in our systems, leading to slower payment processing. Well-formed IDs keep transactions moving at full speed.
Field naming across APIs​
The identifier is the same concept across all Vipps MobilePay APIs — only the field name differs. It is called reference in the ePayment API, and orderId in the eCom, Order Management, and Recurring APIs. Use whichever matches the API you are integrating with.
Requirements and recommendations​
| Property | Rule |
|---|---|
| Uniqueness | Must be unique per sales unit (Merchant Serial Number, MSN). Different sales units may reuse the same value. |
| Case sensitivity | The value is case-sensitive — Order-1 and order-1 are treated as different identifiers. |
| Length | Minimum 6 characters recommended; maximum 64 characters. |
| Allowed characters | a–z, A–Z, 0–9, and dash (-). Example: acme-shop-order-1042 or 2c2a838c-5a88-4b3a-ab9f-e884b92b9bec. |
| Avoid leading zeros | Leading zeros may be stripped by tools such as Excel, causing reconciliation mismatches. |
| Avoid purely numeric IDs | Short all-numeric IDs (e.g., 12345) are difficult to locate in logs and slow to process. Mix letters and numbers. |
Short payment IDs with only a few digits cause extra processing overhead and slower performance. IDs that follow the format guidelines above process at full speed.
Structuring IDs for scale​
Multiple sales units​
Prefix the identifier with the MSN for each sales unit. This ensures uniqueness across units and makes cross-unit reporting trivial — every transaction is instantly attributable to the correct unit.
Example: For MSN 654321, use 654321-acme-shop-order123abc.
Multiple stores under one sales unit​
If several stores share a single sales unit, prefix the identifier with a store-specific code of your choosing. This gives you the ability to filter and report on individual stores without any additional data mapping.
Example: store001-order456xyz
Handling multiple payment attempts for the same order​
Customers sometimes cancel a payment and try again — for example, after modifying their cart. Because each payment attempt requires a unique identifier, append an incrementing suffix to your internal order ID:
| Attempt | Vipps / MobilePay identifier |
|---|---|
| 1st | acme-shop-123-order123abc-1 |
| 2nd | acme-shop-123-order123abc-2 |
| 3rd | acme-shop-123-order123abc-3 |
The base ID (acme-shop-123-order123abc) remains consistent, so you can search for it on the business portal and immediately see all related attempts — no data joins required.