Quick start

NOTICE

All new integrations should use the ePayment API. See the eCom to ePayment Migration guide for help migrating older integrations.

Only available for Vipps.

Before you begin

Important: We strongly recommend that you use the newer ePayment API instead.

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. Note that any currency amount must be an Integer value minimum 100 in øre.

Your first Payment

Step 1 - Setup

You must have already signed up as an organization with Vipps MobilePay and have your API keys. 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 secret for a test sales unit.
Ocp-Apim-Subscription-Key - The subscription key for a sales unit.
merchantSerialNumber - The unique ID for a sales unit.

You will also need:

mobileNumber - The phone number for your test user.

curl
Postman

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:

Import the following files:
- eCom API Postman collection
- Global Postman environment
Select to use the imported global environment.
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

No additional setup needed :)

Step 2 - Get an access token

For all the following, you will need an access_token from the Access token API: POST:/accesstoken/get. This provides you with access to the API.

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 - Initiate a payment

Initiate a payment with: POST:/ecomm/v2/payments. When your test mobile number is provided in phoneNumber, it will be prefilled in the form.

curl
Postman

Send request "Initiate Payment"

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: 0f14ebcab0ec4b29ae0cb90d91b4a84a" \
-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": "UNIQUE-PAYMENT-REFERENCE",
    "transactionText": "One pair of socks.",
  }
}'

Note that orderId must be unique for each payment you create.

Step 4 - Complete the payment

Ctrl+click (Command-click on macOS) on the link that appears, and it will take you to the landing page. The phone number of your test user should already be filled in, so you only have to click Next. You will be presented with the payment in the app, where you can complete or reject the payment. Once you have acted upon the payment, you will be redirected back to the specified fallBack URL under a "best effort" policy.

note

We cannot guarantee the user will be redirected back to the same browser or session, or that they will at all be redirected back. User interaction can be unpredictable, and the user may choose to fully close the app or browser.

Step 5 - Get the status of the payment

To receive the result of the user action you may poll the status of the payment via the GET:/ecomm/v2/payments/{orderId}/details.

curl
Postman

Send request "Get Payment Details"

curl -X GET https://apitest.vipps.no/ecomm/v2/payments/UNIQUE-PAYMENT-REFERENCE/details \
-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" \

Step 6 - Capture the payment

After the goods or services have been delivered, you can capture the authorized amount either partially or fully: POST:/ecomm/v2/payments/{orderId}/capture.

curl
Postman

Send request "Capture payment"

curl -X POST https://apitest.vipps.no/ecomm/v2/payments/UNIQUE-PAYMENT-REFERENCE/capture \
-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 "X-Request-Id: YOUR-IDEMPOTENCY-KEY" \
-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 '{
    "merchantInfo": {
        "merchantSerialNumber": "123456"
    },
    "transaction": {
        "transactionText": "This transaction was captured."
    }
}'

See Knowledge base: Capture for more details.

Optional steps

Refund the payment

To refund the captured amount, either partially or fully: POST:/ecomm/v2/payments/{orderId}/refund.

curl
Postman

Send request "Refund payment"

curl -X POST  https://apitest.vipps.no/ecomm/v2/payments/UNIQUE-PAYMENT-REFERENCE/refund \
-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 'X-Request-Id: YOUR-IDEMPOTENCY-KEY' \
-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 '{
  "merchantInfo": {
        "merchantSerialNumber": "123456"
    },
    "transaction": {
        "transactionText":"This payment was refunded."
    }
}'

See Knowledge base: refund for more details.

Cancel the payment

To cancel the payment, either fully or after a partial capture: POST:/ecomm/v2/payments/{orderId}/cancel.

curl
Postman

Send request "Cancel payment"

curl -X PUT https://apitest.vipps.no/ecomm/v2/payments/UNIQUE-PAYMENT-REFERENCE/cancel \
-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 '{
  "merchantInfo": {
        "merchantSerialNumber": "123456"
    },
    "transaction": {
        "transactionText":"This payment was cancelled."
    }
}'

See Knowledge base: Cancel for more details.

Next Steps

You will find more examples of eCom API requests in the eCom API Postman collection.

Experiment with these or go straight to the eCom API Guide.

Before you begin​

Your first Payment​

Step 1 - Setup​

Step 2 - Get an access token​

Step 3 - Initiate a payment​

Step 4 - Complete the payment​

Step 5 - Get the status of the payment​

Step 6 - Capture the payment​

Optional steps​

Refund the payment​

Cancel the payment​

Next Steps​