Quick start

Use the Order Management API to generate enriched receipts.

Before you begin

The provided example values in this guide must be changed with the values for your sales unit and user. This applies for API keys, HTTP headers, reference, phone number, etc.

Your first receipt

Step 1 - Setup

You must have already signed up as an organization with Vipps MobilePay and have your test credentials from the merchant portal. See Getting started guide for help.

Get these API key values for your sales unit (How to find the API keys):

• client_id - Client_id for a test sales unit.
• client_secret - Client_id for a test sales unit.
• Ocp-Apim-Subscription-Key - Subscription key for a test sales unit.
• merchantSerialNumber - The unique ID for a test sales unit.

You will also need this for the eCom API requests:

• MobileNumber - The phone number for the test app profile you have received or registered. This is your test mobile number without country code.

curl

warning

🔥 Do not store production keys in the Postman cloud. 🔥

To prevent your sensitive data and credentials from being synced to the Postman cloud, store them in the Current Value fields of your Postman environment.

Open Postman and do the following:

1. Import the following files:

   • Order Management API Postman collection
   • API Global Postman environment

2. Select to use the imported global environment.

3. In the global environment, update only the Current Value field with your own values for the following:

   • client_id
   • client_secret
   • Ocp-Apim-Subscription-Key
   • merchantSerialNumber
   • MobileNumber

Postman

No additional setup needed :)

Step 2 - Get an access token

Get an access_token from the Access token API: POST:/accesstoken/get.

curl

Send request Get Access Token

Postman

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' \
-H 'Vipps-System-Name: YOUR-SYSTEM-NAME' \
-H 'Vipps-System-Version: YOUR-SYSTEM-VERSION' \
-H 'Vipps-System-Plugin-Name: YOUR-PLUGIN-NAME' \
-H 'Vipps-System-Plugin-Version: YOUR-PLUGIN-VERSION' \
--data ''

For an explanation of the headers, see HTTP headers.

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.

curl

Send request Initiate Payment

Postman

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

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 a receipt directly in the ePayment API createPayment request, 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 receipt first, then create the payment request afterwards.

Step 4 - (Optional) Upload an image

Upload an image with: POST:/order-management/v1/images. This image can be used in one or many receipts.

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

curl

Send request Upload an image

Postman

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 an order

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

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

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

curl

Send request Add category to an order

Postman

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 for details.

Step 7 - Add receipt to the payment

Set all details about the receipt with: POST:/order-management/v2/{paymentType}/receipts/{orderId}.

A receipt is 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.

curl

Send request Add receipt to an order

Postman

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": 2550,
    },
  ],
  "bottomLine": {
    "currency": "NOK",
  }
}'

See API guide: Receipts for more details.

Step 8 - (Optional) Fetch the receipt

Fetch the details stored about the order and the receipt by using GET:/order-management/v2/{paymentType}/{orderId}.

curl

Send request Get order with category and receipt

Postman

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 to read about the concepts and details.