orderId / reference recommendations

The orderId / reference are fields used to identify a transaction. These are the same concept with different names and are used in the APIs as follows:

• eCom API - orderId
• ePayment API - reference
• Order Management API - orderId
• Recurring API - orderId

Requirements for orderId / reference

The value must be unique for a sales unit (i.e., Merchant Serial Number); however, several MSNs may use the same orderId/reference, as long as it is unique for each sales unit.

The orderId/reference is case-sensitive.

If you ever have a problem that requires us to search in our logs, we will need orderId values that are "unique enough" to actually find them. An orderId that is just a number may not be possible to find.

While the minimum length for orderId technically is just one character, we strongly recommend using at least 6 characters, and a combination of numbers and characters.

The maximum length of an orderId is 64, and can contain alphanumeric characters and dashes: a-z, A-Z, 0-9, -. Example: 2c2a838c-5a88-4b3a-ab9f-e884b92b9bec.

We strongly recommend to use orderId format that makes it easy to search for them in logs. This means that abc123def456 is a better format than 123456.

Leading zeros should be avoided, as some applications (like Excel) tend to remove them, and this may cause misunderstandings.

With multiple sales units, prefixing the orderId with the MSN for each sales unit is recommended: If the MSN is 654321, the orderId values could start at 654321000000000001 and increment by 1 for each order, or some similar, unique and readable pattern.

note

Having very short order IDs, with just a few digits, can cause internal processing in the Vipps MobilePay systems to be slower, and this can cause problems, such as timeouts. Use the recommended format to avoid problems.

The orderId / reference can be seen in the app for Vipps users (only), if it's provided in the API request.

tip

For more screenshots of the payment screen, see Recurring API: Create agreement.

Use user-friendly order IDs

If you ever have a problem that requires us to search in our logs, we need a reference that is unique enough to actually find. A reference that contains only digits may not be possible to find, and then we are not able to help.

It is possible to use UUID, of the format 123e4567-e89b-12d3-a456-426614174000, but remember that reference is shown to the user in Vipps MobilePay. We recommend a more user-friendly format, like acme-shop-123-order123abc.

The maximum length of a reference is 64 alphanumeric characters: a-z, A-Z, 0-9 and - (hyphen). Leading zeros should be avoided, as some applications (e.g., Excel) tend to remove them, and this may cause misunderstandings.

See also: Recommendations for paymentDescription and transactionText.

Multiple sales units

If you have multiple sales units, prefixing the reference with the MSN for each sales unit is recommended. For example, if the MSN is 654321, the reference could be 654321-acme-shop-123-order123abc.

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.

If you use a suffix, you will still be able to search for the main part of the orderId on portal.vippsmobilepay.com, like acme-shop-123-order123abc, without the suffix, and still get find the orderId acme-shop-123-order123abc-1.