orderId / reference recommendations

Recommendations for choosing values for the payment identifier (orderId / reference) in API calls.
These guidelines help ensure that each transaction is uniquely and reliably identified across all Vipps MobilePay APIs.

Field naming across APIs

The orderId / reference fields are used to identify a transaction.
They represent the same concept, but the name varies depending on the API:

API	Field Name
eCom API	orderId
ePayment API	reference
Order Management API	orderId
Recurring API	orderId

tip

Both orderId and reference serve as unique transaction identifiers. Just use the field name that matches the API you’re integrating with.

Requirements for orderId / reference

To keep things running smoothly—and make troubleshooting easier—please follow these guidelines when setting the orderId and reference:

• Unique per Sales Unit

  • The value must be unique for each sales unit (Merchant Serial Number, MSN).
  • Multiple MSNs can use the same orderId/reference, as long as it’s unique within each sales unit.

• Case Sensitivity

  • The orderId/reference is case-sensitive.

• Log Searchability

  • If you need assistance, we use the orderId/reference to search our logs.
  • Please choose values that are “unique enough” and easy to find—numeric strings alone (like 12345) can be hard to track down.
  • Mix numbers and letters for better searchability.

• Length and Format

  • Minimum: We recommend at least 6 characters for clarity and uniqueness
  • Maximum: 64 characters
  • Allowed characters: a-z, A-Z, 0-9, and dash (-)
    • Example: 2c2a838c-5a88-4b3a-ab9f-e884b92b9bec

• Best Practices

  • Use a format that’s easy to search (e.g., abc123def456 is better than 123456).
  • Avoid leading zeros—they can be removed by some apps (like Excel), causing confusion.
  • For multiple sales units, prefix the orderId/reference with the MSN.
    • For MSN 654321, use values like 654321000000000001, incrementing for each order, or choose a similar unique and readable pattern.

note

Please use payment identifiers that follow the recommended format guidelines above. Short payment IDs, with just a few digits, causes extra processing leading to slower performance.

Reference number in the app

The orderId / reference is shown to the user in the Vipps app, so we recommend a user-friendly format, like acme-shop-123-order123abc.

For more screenshots, see:

• Recurring API: Create agreement
• ePayment API: Payments

Multiple sales units

If you operate with multiple sales units, we recommend prefixing the orderId or reference with the MSN for each unit.
For example, if the MSN is 654321, the reference could be: 654321-acme-shop-123-order123abc.

This helps ensure uniqueness and makes logs and reports easier to search.

Multiple stores per one sales unit

If you have several stores under a single sales unit, prefix the orderId or reference with a unique ID for each store (defined by you).
This way, you can easily locate transaction data for each store in reports by searching for the store’s unique ID.

For example: store001-order456xyz.

Multiple attempts

If you need to make multiple attempts at paying the "same" order, you can add a suffix to the orderId to make it unique.

For example, if your internal orderId is acme-shop-123-order123abc, you can add -1 to get a unique Vipps orderId acme-shop-123-order123abc-1 for the first attempt, acme-shop-123-order123abc-2 for the second, etc.

This is useful when a customer does the following:

1. Adds a product to the cart.
2. Goes to the payment page and selects Vipps or MobilePay .
3. Gets the payment request in the app, but cancels (or does nothing).
4. Adds another product to the same cart (or order).
5. Repeat steps 2 and 3.

By using a suffix, you keep each payment attempt unique and easily searchable.
You can still search for the main part of the orderId — for example, acme-shop-123-order123abc— on portal.vippsmobilepay.com and find all related attempts.