> **Description:** A step-by-step guide to quickly implement the Order Management API, including authentication setup, basic API calls, and essential features for managing order information.

# Quick start

This guide takes you through all the Order Management API requests.
Use the Order Management API to generate enriched transaction details.

## Before you begin

Sign up as an organization with Vipps MobilePay and get your API keys.

You will need the [sales unit API keys](https://developer.vippsmobilepay.com/docs/knowledge-base/api-keys.md) for a *test* sales unit:

* `client_id` - Client ID for the sales unit.
* `client_secret` - Client secret for the sales unit.
* `Ocp-Apim-Subscription-Key` - Subscription key for the sales unit.
* `merchantSerialNumber` - The unique ID (MSN) for the sales unit.

[Partner keys](https://developer.vippsmobilepay.com/docs/partner/partner-keys.md#partner-keys) only work in the production environment.
To follow this guide in the test environment, use the test sales unit API keys provided in your welcome email.

In production, partner keys are used exactly like sales unit API keys, with one difference:
the `Merchant-Serial-Number` header is *required*, not just recommended.

If you're new to the platform, see
[Getting started](https://developer.vippsmobilepay.com/docs/getting-started.md)
for information about API keys, product activation, and the test environment.

The example values in this guide must be replaced with the values for your sales unit and user.
This applies to API keys, HTTP headers, references, phone numbers, and similar values.

## Your first payment including order details

### Step 1 - Setup

If using Postman, download the following files and import them into Postman.
Select the global environment as your active environment and update with your own values for the API keys and mobile numbers (both with and without country code). *Don't store production keys in the cloud.*

* [Download Order Management API Postman collection](https://developer.vippsmobilepay.com/tools/order-management-api-postman-collection.json)
* [Download Global Postman environment](https://developer.vippsmobilepay.com/tools/global-postman-environment.json)

### Step 2 - Get an access token

Get an `access_token` from the
[Access Token API](https://developer.vippsmobilepay.com/docs/APIs/access-token-api/README.md):
[`POST:/accesstoken/get`][access-token-endpoint].

```text
Send request "Get Access Token"
```

```bash
curl -X POST 'https://apitest.vipps.no/accesstoken/get' \
-H "Content-Type: application/json" \
-H 'client_id: YOUR-CLIENT-ID' \
-H 'client_secret: YOUR-CLIENT-SECRET' \
-H 'Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY' \
-H 'Merchant-Serial-Number: YOUR-MSN' \
--data ''
```

In production, include all `Vipps-System` headers to aid debugging.
See [HTTP headers](https://developer.vippsmobilepay.com/docs/knowledge-base/http-headers.md) for details.

The property `access_token` should be used as the Bearer token in the `Authorization` header of all the following API requests.

### Step 3 - Request a payment

Create a payment with either the eCom API or Recurring API.

Provide unique values for `Idempotency-Key` and `orderId` each time you request a payment.

```text
Send request "Initiate Payment"
```

You need to create a payment with either the eCom API or the Recurring API.
Here is an example with the eCom API.

```bash
curl -X POST 'https://apitest.vipps.no/ecomm/v2/payments/' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
-H 'Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY' \
-H 'Merchant-Serial-Number: YOUR-MSN' \
-H 'Vipps-System-Name: acme' \
-H 'Vipps-System-Version: 3.1.2' \
-H 'Vipps-System-Plugin-Name: acme-webshop' \
-H 'Vipps-System-Plugin-Version: 4.5.6' \
-d '{
  "customerInfo": {
    "mobileNumber": "12345678"
  },
  "merchantInfo": {
    "merchantSerialNumber": "123456",
    "callbackPrefix":"https://example.com/vipps/callbacks-for-payment-update-from-vipps",
    "fallBack": "https://example.com/vipps/fallback-result-page-for-both-success-and-failure/acme-shop-123-order123abc",
  },
  "transaction": {
    "amount": 49900,
    "orderId": "PAYMENT-ORDER-ID",
    "transactionText": "One pair of socks.",
}
}'
```

Note that you can also create order details directly in the
[ePayment API `createPayment` request](https://developer.vippsmobilepay.com/redocusaurus/epayment-swagger-id.yaml),
but to add a category and image, you will use the steps below.

**Please note:**
The payment doesn't need to exist yet. It is possible to add the order details first, then create the payment request afterwards.

### Step 4 - (Optional) Upload an image

Upload an image with: [`POST:/order-management/v1/images`][post-image-endpoint].
This image can be reused.

Provide an image in base64 format. Specify a unique `imageId`.

```text
Send request "Upload an image"
```

```bash
curl -X POST https://apitest.vipps.no/order-management/v1/images \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
-H "Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY" \
-H "Merchant-Serial-Number: YOUR-MSN" \
-H "Vipps-System-Name: acme" \
-H "Vipps-System-Version: 3.1.2" \
-H "Vipps-System-Plugin-Name: acme-webshop" \
-H "Vipps-System-Plugin-Version: 4.5.6" \
-d '{
  "imageId": "logo-12345678",
  "src": "iVBORw0KGgoAAAANSUhEUgAAAMgAAADJCAYA <truncated>",
  "type": "base64"
}'
```

You can see the image in the payment history of the app, once you create a category and attach it to the payment.

### Step 6 - Add category to the payment

Set the category, image, and order details URL by using
[`PUT:/order-management/v2/{paymentType}/categories/{orderId}`][put-category-endpoint].

Use `ecom` for the `paymentType` of ePayment or eCom payments. Use `recurring` for recurring payments.
For `orderId`, use the `orderId` or `reference` (for the ePayment API) of the payment.

The category is mutable, and a new request will completely overwrite previous requests.

```text
Send request "Add a category"
```

```bash
curl -X PUT https://apitest.vipps.no/order-management/v2/ecom/categories/PAYMENT-ORDER-ID \
-H "Content-Type: application/json" \
-H "Authorization: YOUBearer YOUR-ACCESS-TOKEN" \
-H "Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY" \
-H "Merchant-Serial-Number: YOUR-MSN" \
-H "Vipps-System-Name: acme" \
-H "Vipps-System-Version: 3.1.2" \
-H "Vipps-System-Plugin-Name: acme-webshop" \
-H "Vipps-System-Plugin-Version: 4.5.6" \
-d '{
   "category": "GENERAL",
   "orderDetailsUrl": "https://www.example.com/2486791691483852025",
   "imageId": "logo-12345678"
}'
```

See [API guide: Categories](https://developer.vippsmobilepay.com/docs/APIs/order-management-api/order-management-api-guide.md#categories) for details.

### Step 7 - Add order details to the payment

Set order details using:
[`POST:/order-management/v2/{paymentType}/receipts/{orderId}`][post-receipt-endpoint].

Order details are immutable and, once sent, cannot be overwritten.
So, if you want to run this example more than once, you'll need to create a new payment request to attach it to.

```text
Send request "Add order details"
```

```bash
curl -X POST https://apitest.vipps.no/order-management/v2/ecom/receipts/PAYMENT-ORDER-ID \
-H "Content-Type: application/json" \
-H "Authorization: YOUBearer YOUR-ACCESS-TOKEN" \
-H "Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY" \
-H "Merchant-Serial-Number: YOUR-MSN" \
-H "Vipps-System-Name: acme" \
-H "Vipps-System-Version: 3.1.2" \
-H "Vipps-System-Plugin-Name: acme-webshop" \
-H "Vipps-System-Plugin-Version: 4.5.6" \
-d '{
  "orderLines": [
    {
      "name": "Socks",
      "id": "socks_123456789",
      "totalAmount": 1000,
      "totalAmountExcludingTax": 800,
      "totalTaxAmount": 200,
      "taxRate": 2500,
    },
  ],
  "bottomLine": {
    "currency": "NOK",
  }
}'
```

For more details, see [API guide: Adding order details](https://developer.vippsmobilepay.com/docs/APIs/order-management-api/order-management-api-guide.md#adding-order-details).

### Step 8 - (Optional) Get the order details

Fetch the details stored about the order by using
[`GET:/order-management/v2/{paymentType}/{orderId}`][get-order-endpoint].

```text
Send request "Get payment details"
```

```bash
curl -X GET https://apitest.vipps.no/order-management/v2/ecom/payment12345 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
-H "Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY" \
-H "Merchant-Serial-Number: YOUR-MSN" \
-H "Vipps-System-Name: acme" \
-H "Vipps-System-Version: 3.1.2" \
-H "Vipps-System-Plugin-Name: acme-webshop" \
-H "Vipps-System-Plugin-Version: 4.5.6" \
-d ''
```

## Next steps

Visit the [Order Management API Guide](https://developer.vippsmobilepay.com/docs/APIs/order-management-api/order-management-api-guide.md) to read about the concepts and details.

[post-image-endpoint]: https://developer.vippsmobilepay.com/redocusaurus/order_management-swagger-id.yaml
[put-category-endpoint]: https://developer.vippsmobilepay.com/redocusaurus/order_management-swagger-id.yaml
[post-receipt-endpoint]: https://developer.vippsmobilepay.com/redocusaurus/order_management-swagger-id.yaml
[get-order-endpoint]: https://developer.vippsmobilepay.com/redocusaurus/order_management-swagger-id.yaml
[access-token-endpoint]: https://developer.vippsmobilepay.com/redocusaurus/access-token-swagger-id.yaml
[ecom-create-payment-endpoint]: https://developer.vippsmobilepay.com/redocusaurus/ecom-swagger-id.yaml

> **Full site overview:** For every page in this documentation, read [https://developer.vippsmobilepay.com/llms.txt](https://developer.vippsmobilepay.com/llms.txt).