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:
client_id
- Client_id for a test sales unit.client_secret
- Client secret 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.
If you're new to the platform, see Getting started for information about API keys, product activation, and the test environment.
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 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 the Current Value field with your own values for the API keys and mobile numbers (both with and without country code). 🔥 Do not store production keys in the cloud. 🔥
Step 2 - Get an access token​
Get an access_token
from the
Access token API:
POST:/accesstoken/get
.
- curl
- Postman
Send request "Get Access Token"
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 ''
For production, include all the Vipps-System
headers so that we can help with debugging any problems.
For details, 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
- Postman
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.
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,
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
.
This image can be reused.
Provide an image in base64 format. Specify a unique imageId
.
- curl
- Postman
Send request "Upload an image"
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}
.
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.
- curl
- Postman
Send request "Add a category"
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 order details to the payment​
Set order details using:
POST:/order-management/v2/{paymentType}/receipts/{orderId}
.
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.
- curl
- Postman
Send request "Add order details"
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.
Step 8 - (Optional) Get the order details​
Fetch the details stored about the order by using
GET:/order-management/v2/{paymentType}/{orderId}
.
- curl
- Postman
Send request "Get payment details"
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.