Order Management API (2.1)

Download OpenAPI specification:Download

URL: https://developer.vippsmobilepay.com/docs/contact/

The Order Management API enables you to read and add information for Vipps MobilePay orders. See the Order Management API Guide for more details.

Add category to an order

The category adds a link, specified by you, to the Transaction page on the Vipps MobilePay app. Only one (the latest) category is shown in the app.

Authorizations:

BearerToken

path Parameters

paymentType required	string Enum: "ECOM" "RECURRING" The type of transaction {ECOM, RECURRING}. Use "ECOM" for both eCom API and ePayment API payments. Use "RECURRING" for Recurring API payments.
orderId required	string^[0-9A-Za-z-_\.]+$ The orderId of the transaction, unique and managed by merchant

header Parameters

Authorization required	string The access token is a base64-encoded string that is required for all API calls. It is a JWT (JSON Web Token). The access token is fetched from the `POST:/accesstoken/get` endpoint. It is valid for 1 hour in the test environment and 24 hours in the production environment.
Merchant-Serial-Number required	string The merchant serial number for this sales unit.
Ocp-Apim-Subscription-Key required	string The API subscription key.
Vipps-System-Version	string <= 100 characters Example: 5.4.0 The version number of the ecommerce solution. See http-headers.
Vipps-System-Plugin-Name	string <= 100 characters Example: vipps-woocommerce The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. See http-headers.
Vipps-System-Name	string <= 100 characters Example: woocommerce The name of the ecommerce solution. One word in lowercase letters is good. See http-headers.
Vipps-System-Plugin-Version	string <= 100 characters Example: 1.2.1 The version number of the ecommerce plugin (if applicable). See http-headers.

Request Body schema: application/json

category required	string or null (CategoryEnum) Enum: "GENERAL" "RECEIPT" "ORDER_CONFIRMATION" "DELIVERY" "TICKET" "BOOKING"
orderDetailsUrl required	string <uri> non-empty URL linking back to the merchant's website/store.
imageId	string or null [ 1 .. 128 ] characters ^[0-9A-Za-z-_\.]+$

Responses

Request samples

Payload

Content type

application/json

{"category": "GENERAL",
"orderDetailsUrl": "https://example.com",
"imageId": "socks-orange-123"
}

Response samples

200
400
404
409

Content type

application/json

"16328cb8-d769-4c53-90ad-e19777823f0a"

Add category to an order.

The category adds a link, specified by you, to the Transaction page in the Vipps or MobilePay app.

Authorizations:

BearerToken

header Parameters

Authorization required	string The access token is a base64-encoded string that is required for all API calls. It is a JWT (JSON Web Token). The access token is fetched from the `POST:/accesstoken/get` endpoint. It is valid for 1 hour in the test environment and 24 hours in the production environment.
Merchant-Serial-Number required	string The merchant serial number for this sales unit.
Ocp-Apim-Subscription-Key required	string The API subscription key.
Vipps-System-Version	string <= 100 characters Example: 5.4.0 The version number of the ecommerce solution. See http-headers.
Vipps-System-Plugin-Name	string <= 100 characters Example: vipps-woocommerce The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. See http-headers.
Vipps-System-Name	string <= 100 characters Example: woocommerce The name of the ecommerce solution. One word in lowercase letters is good. See http-headers.
Vipps-System-Plugin-Version	string <= 100 characters Example: 1.2.1 The version number of the ecommerce plugin (if applicable). See http-headers.

Request Body schema: application/json

orderId required	string (OrderId) ^[0-9A-Za-z-_\.]+$ The orderId of the transaction, unique and managed by merchant
paymentType required	string (PaymentType) Enum: "ECOM" "RECURRING" The type of transaction {ECOM, RECURRING}. Use "ECOM" for both eCom API and ePayment API payments. Use "RECURRING" for Recurring API payments.
type required	string or null (CategoryEnum) Enum: "GENERAL" "RECEIPT" "ORDER_CONFIRMATION" "DELIVERY" "TICKET" "BOOKING"
url required	string <uri> non-empty URL linking back to the merchant's website/store.
imageId	string [ 1 .. 128 ] characters ^[0-9A-Za-z-_\.]+$

Responses

Request samples

Payload

Content type

application/json

{"orderId": "PaymentReference123",
"paymentType": "ECOM",
"type": "RECEIPT",
"url": "https://www.example.com",
"imageId": "f09c6aeb-442e-4da1-b36a-d8f613edc6c9"
}

Response samples

201
400

Content type

application/json

{"categoryId": "337f5e5d-288b-40d5-be14-901cc3acacc0"
}

Query categories

Query categories by orderId

Authorizations:

BearerToken

query Parameters

orderId

string

The orderId of the transaction, unique and managed by merchant

header Parameters

Authorization required	string The access token is a base64-encoded string that is required for all API calls. It is a JWT (JSON Web Token). The access token is fetched from the `POST:/accesstoken/get` endpoint. It is valid for 1 hour in the test environment and 24 hours in the production environment.
Merchant-Serial-Number required	string The merchant serial number for this sales unit.
Ocp-Apim-Subscription-Key required	string The API subscription key.
Vipps-System-Version	string <= 100 characters Example: 5.4.0 The version number of the ecommerce solution. See http-headers.
Vipps-System-Plugin-Name	string <= 100 characters Example: vipps-woocommerce The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. See http-headers.
Vipps-System-Name	string <= 100 characters Example: woocommerce The name of the ecommerce solution. One word in lowercase letters is good. See http-headers.
Vipps-System-Plugin-Version	string <= 100 characters Example: 1.2.1 The version number of the ecommerce plugin (if applicable). See http-headers.

Responses

Response samples

200
400

Content type

application/json

{"categories": [{"categoryId": "880f5088-7708-4a5a-87d9-31e83aacc035",
"orderId": "PaymentReference123",
"paymentType": "ECOM",
"type": "RECEIPT",
"url": "https://www.example.com",
"imageId": "f09c6aeb-442e-4da1-b36a-d8f613edc6c9"
}
]
}

Query category

Query a category by its id

Authorizations:

BearerToken

path Parameters

categoryId

required

string <uuid>

The id of the category

header Parameters

Authorization required	string The access token is a base64-encoded string that is required for all API calls. It is a JWT (JSON Web Token). The access token is fetched from the `POST:/accesstoken/get` endpoint. It is valid for 1 hour in the test environment and 24 hours in the production environment.
Merchant-Serial-Number required	string The merchant serial number for this sales unit.
Ocp-Apim-Subscription-Key required	string The API subscription key.
Vipps-System-Version	string <= 100 characters Example: 5.4.0 The version number of the ecommerce solution. See http-headers.
Vipps-System-Plugin-Name	string <= 100 characters Example: vipps-woocommerce The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. See http-headers.
Vipps-System-Name	string <= 100 characters Example: woocommerce The name of the ecommerce solution. One word in lowercase letters is good. See http-headers.
Vipps-System-Plugin-Version	string <= 100 characters Example: 1.2.1 The version number of the ecommerce plugin (if applicable). See http-headers.

Responses

Response samples

200
400
404

Content type

application/json

{"categoryId": "880f5088-7708-4a5a-87d9-31e83aacc035",
"orderId": "PaymentReference123",
"paymentType": "ECOM",
"type": "RECEIPT",
"url": "https://www.example.com",
"imageId": "f09c6aeb-442e-4da1-b36a-d8f613edc6c9"
}

Delete category

Delete a category by its id

Authorizations:

BearerToken

path Parameters

categoryId

required

string <uuid>

The id of the category

header Parameters

Authorization required	string The access token is a base64-encoded string that is required for all API calls. It is a JWT (JSON Web Token). The access token is fetched from the `POST:/accesstoken/get` endpoint. It is valid for 1 hour in the test environment and 24 hours in the production environment.
Merchant-Serial-Number required	string The merchant serial number for this sales unit.
Ocp-Apim-Subscription-Key required	string The API subscription key.
Vipps-System-Version	string <= 100 characters Example: 5.4.0 The version number of the ecommerce solution. See http-headers.
Vipps-System-Plugin-Name	string <= 100 characters Example: vipps-woocommerce The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. See http-headers.
Vipps-System-Name	string <= 100 characters Example: woocommerce The name of the ecommerce solution. One word in lowercase letters is good. See http-headers.
Vipps-System-Plugin-Version	string <= 100 characters Example: 1.2.1 The version number of the ecommerce plugin (if applicable). See http-headers.

Responses

Response samples

404

Content type

application/json

{"type": "string",
"title": "string",
"detail": "string",
"instance": "string",
"invalidParams": [{"name": "string",
"reason": "string"
}
]
}

Image

Add an image

Endpoint for uploading images. A imageId will be returned that can be used when adding metadata to orders.

Authorizations:

BearerToken

header Parameters

Authorization required	string The access token is a base64-encoded string that is required for all API calls. It is a JWT (JSON Web Token). The access token is fetched from the `POST:/accesstoken/get` endpoint. It is valid for 1 hour in the test environment and 24 hours in the production environment.
Merchant-Serial-Number required	string The merchant serial number for this sales unit.
Ocp-Apim-Subscription-Key required	string The API subscription key.
Vipps-System-Version	string <= 100 characters Example: 5.4.0 The version number of the ecommerce solution. See http-headers.
Vipps-System-Plugin-Name	string <= 100 characters Example: vipps-woocommerce The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. See http-headers.
Vipps-System-Name	string <= 100 characters Example: woocommerce The name of the ecommerce solution. One word in lowercase letters is good. See http-headers.
Vipps-System-Plugin-Version	string <= 100 characters Example: 1.2.1 The version number of the ecommerce plugin (if applicable). See http-headers.

Request Body schema: application/json

imageId required	string <= 128 characters ^[0-9A-Za-z-_\.]+$ Id of the image to be added
src required	string The image data as a base64 encoded string (not a URL). The image must be in PNG or JPEG format. Square images are recommended. Minimum height is 167px, and max file size is 2MB.
type required	string Value: "base64"

Responses

Request samples

Payload

Content type

application/json

{"imageId": "f09c6aeb-442e-4da1-b36a-d8f613edc6c9",
"src": "a3NhbGZuc2FrbGZubGthc25ma2Fuc2ZsYXNuZmxrYXNuZmw=",
"type": "base64"
}

Response samples

200

Content type

application/json

{"imageId": "socks-orange-123"
}

Order

Get order with category and receipt

Authorizations:

BearerToken

path Parameters

paymentType required	string Enum: "ECOM" "RECURRING" The type of transaction {ECOM, RECURRING}. Use "ECOM" for both eCom API and ePayment API payments. Use "RECURRING" for Recurring API payments.
orderId required	string^[0-9A-Za-z-_\.]+$ The orderId of the transaction, unique and managed by merchant

header Parameters

Authorization required	string The access token is a base64-encoded string that is required for all API calls. It is a JWT (JSON Web Token). The access token is fetched from the `POST:/accesstoken/get` endpoint. It is valid for 1 hour in the test environment and 24 hours in the production environment.
Merchant-Serial-Number required	string The merchant serial number for this sales unit.
Ocp-Apim-Subscription-Key required	string The API subscription key.
Vipps-System-Version	string <= 100 characters Example: 5.4.0 The version number of the ecommerce solution. See http-headers.
Vipps-System-Plugin-Name	string <= 100 characters Example: vipps-woocommerce The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. See http-headers.
Vipps-System-Name	string <= 100 characters Example: woocommerce The name of the ecommerce solution. One word in lowercase letters is good. See http-headers.
Vipps-System-Plugin-Version	string <= 100 characters Example: 1.2.1 The version number of the ecommerce plugin (if applicable). See http-headers.

Responses

Response samples

200
404

Content type

application/json

{"category": {"category": "RECEIPT",
"orderDetailsUrl": "https://www.example.com",
"imageId": "socks-orange-123"
},
"receipt": {"orderLines": [{"name": "socks",
"id": "1234567890",
"totalAmount": 1000,
"totalAmountExcludingTax": 800,
"totalTaxAmount": 250,
"taxPercentage": 25,
"taxRate": 2500,
"unitInfo": {"unitPrice": 0,
"quantity": "0.822",
"quantityUnit": "PCS"
},
"discount": 2000,
"productUrl": "https://example.com/store/socks",
"isReturn": false,
"isShipping": false
}
],
"bottomLine": {"currency": "NOK",
"tipAmount": 2000,
"giftCardAmount": 20000,
"posId": "string",
"totalAmount": 0,
"totalTax": 0,
"totalDiscount": 0,
"shippingAmount": 0,
"shippingInfo": {"amount": 1000,
"amountExcludingTax": 1000,
"taxAmount": 250,
"taxPercentage": 25
},
"paymentSources": {"giftCard": 0,
"card": 0,
"voucher": 0,
"cash": 0
},
"barcode": {"format": "EAN-13",
"data": "string"
},
"receiptNumber": "string",
"terminalId": "string"
}
}
}

Receipt

Add receipt to an order

Add receipt to an order.

Authorizations:

BearerToken

path Parameters

orderId required	string^[0-9A-Za-z-_\.]+$ The orderId of the transaction, unique and managed by merchant
paymentType required	string Enum: "ECOM" "RECURRING" The type of transaction {ECOM, RECURRING}. Use "ECOM" for both eCom API and ePayment API payments. Use "RECURRING" for Recurring API payments.

header Parameters

Authorization required	string The access token is a base64-encoded string that is required for all API calls. It is a JWT (JSON Web Token). The access token is fetched from the `POST:/accesstoken/get` endpoint. It is valid for 1 hour in the test environment and 24 hours in the production environment.
Merchant-Serial-Number required	string The merchant serial number for this sales unit.
Ocp-Apim-Subscription-Key required	string The API subscription key.
Vipps-System-Version	string <= 100 characters Example: 5.4.0 The version number of the ecommerce solution. See http-headers.
Vipps-System-Plugin-Name	string <= 100 characters Example: vipps-woocommerce The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. See http-headers.
Vipps-System-Name	string <= 100 characters Example: woocommerce The name of the ecommerce solution. One word in lowercase letters is good. See http-headers.
Vipps-System-Plugin-Version	string <= 100 characters Example: 1.2.1 The version number of the ecommerce plugin (if applicable). See http-headers.

Request Body schema: application/json

required	Array of objects (OrderLine) non-empty Amounts are specified in minor units (i.e., integers with two trailing zeros). For example: 10.00 EUR/NOK/DKK should be written as 1000.
required	object (BottomLine) Summary of the order. Total amount and total. Amounts are specified in minor units (i.e., integers with two trailing zeros). For example: 10.00 EUR/NOK/DKK should be written as 1000.

Responses

Request samples

Payload

Content type

application/json

{"orderLines": [{"name": "socks",
"id": "line_item_1",
"totalAmount": 1000,
"totalAmountExcludingTax": 800,
"totalTaxAmount": 200,
"taxPercentage": 25,
"unitInfo": {"unitPrice": 400,
"quantity": "2.5",
"quantityUnit": "KG"
},
"discount": 0,
"productUrl": "https://example.com/store/socks",
"isReturn": false,
"isShipping": false
},
{"name": "flip-flops",
"id": "line_item_2",
"totalAmount": 5000,
"totalAmountExcludingTax": 4000,
"totalTaxAmount": 1000,
"taxPercentage": 25,
"unitInfo": {"unitPrice": 2500,
"quantity": "3",
"quantityUnit": "PCS"
},
"discount": 2500,
"productUrl": "https://example.com/store/flipflops",
"isReturn": false,
"isShipping": false
},
{"name": "Home Delivery",
"id": "delivery",
"totalAmount": 1000,
"totalAmountExcludingTax": 800,
"totalTaxAmount": 200,
"taxPercentage": 25,
"discount": 0,
"isReturn": false,
"isShipping": true
}
],
"bottomLine": {"currency": "NOK",
"tipAmount": 0,
"posId": "pos_122",
"paymentSources": {"giftCard": 0,
"card": 0,
"voucher": 0,
"cash": 0
},
"barcode": {"format": "CODE 39",
"data": "SC0527013501 "
},
"receiptNumber": "0527013501"
}
}

Response samples

201
400
404
409

Content type

application/json

"16328cb8-d769-4c53-90ad-e19777823f0a"

Deprecated endpoints

No longer available

Add info to an order Deprecated

Post additional information about an order that will show up on the receipt.

Authorizations:

BearerToken

path Parameters

transactionId

required

string

header Parameters

Authorization required	string The access token is a base64-encoded string that is required for all API calls. It is a JWT (JSON Web Token). The access token is fetched from the `POST:/accesstoken/get` endpoint. It is valid for 1 hour in the test environment and 24 hours in the production environment.
Merchant-Serial-Number required	string The merchant serial number for this sales unit.
Ocp-Apim-Subscription-Key required	string The API subscription key.
Vipps-System-Version	string <= 100 characters Example: 5.4.0 The version number of the ecommerce solution. See http-headers.
Vipps-System-Plugin-Name	string <= 100 characters Example: vipps-woocommerce The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. See http-headers.
Vipps-System-Name	string <= 100 characters Example: woocommerce The name of the ecommerce solution. One word in lowercase letters is good. See http-headers.
Vipps-System-Plugin-Version	string <= 100 characters Example: 1.2.1 The version number of the ecommerce plugin (if applicable). See http-headers.

Request Body schema: application/json

category required	string or null (CategoryEnum) Enum: "GENERAL" "RECEIPT" "ORDER_CONFIRMATION" "DELIVERY" "TICKET" "BOOKING"
orderDetailsUrl required	string <uri> non-empty URL linking back to the merchant's website/store.
imageId	string or null [ 1 .. 128 ] characters ^[0-9A-Za-z-_\.]+$

Responses

Request samples

Payload

Content type

application/json

{"category": "GENERAL",
"orderDetailsUrl": "https://example.com",
"imageId": "socks-orange-123"
}

Get info for an order Deprecated

Retrieve the metadata for an order

Authorizations:

BearerToken

path Parameters

transactionId

required

string

header Parameters

Authorization required	string The access token is a base64-encoded string that is required for all API calls. It is a JWT (JSON Web Token). The access token is fetched from the `POST:/accesstoken/get` endpoint. It is valid for 1 hour in the test environment and 24 hours in the production environment.
Merchant-Serial-Number required	string The merchant serial number for this sales unit.
Ocp-Apim-Subscription-Key required	string The API subscription key.
Vipps-System-Version	string <= 100 characters Example: 5.4.0 The version number of the ecommerce solution. See http-headers.
Vipps-System-Plugin-Name	string <= 100 characters Example: vipps-woocommerce The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. See http-headers.
Vipps-System-Name	string <= 100 characters Example: woocommerce The name of the ecommerce solution. One word in lowercase letters is good. See http-headers.
Vipps-System-Plugin-Version	string <= 100 characters Example: 1.2.1 The version number of the ecommerce plugin (if applicable). See http-headers.

Responses

Response samples

200

Content type

application/json

{"category": "TICKET",
"orderDetailsUrl": "https://example.com",
"imageIds": [{"id": "socks-orange-123",
"sortOrder": 1
}
]
}

Get receipt for an order Deprecated

Endpoint for retrieving receipts.

Authorizations:

BearerToken

path Parameters

transactionId

required

string

header Parameters

Authorization required	string The access token is a base64-encoded string that is required for all API calls. It is a JWT (JSON Web Token). The access token is fetched from the `POST:/accesstoken/get` endpoint. It is valid for 1 hour in the test environment and 24 hours in the production environment.
Merchant-Serial-Number required	string The merchant serial number for this sales unit.
Ocp-Apim-Subscription-Key required	string The API subscription key.
Vipps-System-Version	string <= 100 characters Example: 5.4.0 The version number of the ecommerce solution. See http-headers.
Vipps-System-Plugin-Name	string <= 100 characters Example: vipps-woocommerce The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. See http-headers.
Vipps-System-Name	string <= 100 characters Example: woocommerce The name of the ecommerce solution. One word in lowercase letters is good. See http-headers.
Vipps-System-Plugin-Version	string <= 100 characters Example: 1.2.1 The version number of the ecommerce plugin (if applicable). See http-headers.

Responses

Response samples

200

Content type

application/json

No sample

Add receipt to an order Deprecated

Endpoint for adding receipts to an order.

Authorizations:

BearerToken

path Parameters

transactionId

required

string

header Parameters

Authorization required	string The access token is a base64-encoded string that is required for all API calls. It is a JWT (JSON Web Token). The access token is fetched from the `POST:/accesstoken/get` endpoint. It is valid for 1 hour in the test environment and 24 hours in the production environment.
Merchant-Serial-Number required	string The merchant serial number for this sales unit.
Ocp-Apim-Subscription-Key required	string The API subscription key.
Vipps-System-Version	string <= 100 characters Example: 5.4.0 The version number of the ecommerce solution. See http-headers.
Vipps-System-Plugin-Name	string <= 100 characters Example: vipps-woocommerce The name of the ecommerce plugin (if applicable). One word in lowercase letters is good. See http-headers.
Vipps-System-Name	string <= 100 characters Example: woocommerce The name of the ecommerce solution. One word in lowercase letters is good. See http-headers.
Vipps-System-Plugin-Version	string <= 100 characters Example: 1.2.1 The version number of the ecommerce plugin (if applicable). See http-headers.

Request Body schema: application/json

required	Array of objects (OrderLine) non-empty Amounts are specified in minor units (i.e., integers with two trailing zeros). For example: 10.00 EUR/NOK/DKK should be written as 1000.
required	object (BottomLine) Summary of the order. Total amount and total. Amounts are specified in minor units (i.e., integers with two trailing zeros). For example: 10.00 EUR/NOK/DKK should be written as 1000.

Responses

Request samples

Payload

Content type

application/json

{"orderLines": [{"name": "socks",
"id": "1234567890",
"totalAmount": 1000,
"totalAmountExcludingTax": 800,
"totalTaxAmount": 250,
"taxPercentage": 25,
"taxRate": 2500,
"unitInfo": {"unitPrice": 0,
"quantity": "0.822",
"quantityUnit": "PCS"
},
"discount": 2000,
"productUrl": "https://example.com/store/socks",
"isReturn": false,
"isShipping": false
}
],
"bottomLine": {"currency": "NOK",
"tipAmount": 2000,
"giftCardAmount": 20000,
"posId": "string",
"totalAmount": 0,
"totalTax": 0,
"totalDiscount": 0,
"shippingAmount": 0,
"shippingInfo": {"amount": 1000,
"amountExcludingTax": 1000,
"taxAmount": 250,
"taxPercentage": 25
},
"paymentSources": {"giftCard": 0,
"card": 0,
"voucher": 0,
"cash": 0
},
"barcode": {"format": "EAN-13",
"data": "string"
},
"receiptNumber": "string",
"terminalId": "string"
}
}

Response samples

400
404

Content type

application/json

{"type": "string",
"title": "string",
"detail": "string",
"instance": "string",
"invalidParams": [{"name": "string",
"reason": "string"
}
]
}

Order Management API (2.1)

Category

Add category to an order

Authorizations:

path Parameters

header Parameters

Request Body schema: application/json

Responses

Request samples

Response samples

Add category to an order.

Authorizations:

header Parameters

Request Body schema: application/json

Responses

Request samples

Response samples

Query categories

Authorizations:

query Parameters

header Parameters

Responses

Response samples

Query category

Authorizations:

path Parameters

header Parameters

Responses

Response samples

Delete category

Authorizations:

path Parameters

header Parameters

Responses

Response samples

Image

Add an image

Authorizations:

header Parameters

Request Body schema: application/json

Responses

Request samples

Response samples

Order

Get order with category and receipt

Authorizations:

path Parameters

header Parameters

Responses

Response samples

Receipt

Add receipt to an order

Authorizations:

path Parameters

header Parameters

Request Body schema: application/json

Responses

Request samples

Response samples

Deprecated endpoints

Add info to an order Deprecated

Authorizations:

path Parameters

header Parameters

Request Body schema: application/json

Responses

Request samples

Get info for an order Deprecated

Authorizations:

path Parameters

header Parameters

Responses

Response samples

Get receipt for an order Deprecated

Authorizations:

path Parameters

header Parameters

Responses

Response samples

Add receipt to an order Deprecated