Quick start

Before you begin

Important: We strongly recommend that all new integrations use the new ePayment API.

This document covers the quick steps for getting started with the ePayment API. You must have already signed up as an organization with Vipps MobilePay and have your test credentials from the merchant portal, as described in the Getting started guide.

Important: The examples use standard example values that you must change to use your values. This includes API keys, HTTP headers, reference, etc.

Your first Payment

Step 1 - Setup

curl
Postman

Please note: Postman is discontinuing their offline version. Use only your test keys and delete them after testing. Ensure that your company allows for cloud use before continuing.

If you wish to use Postman, import the following files:

In Postman, tweak the environment with your own values (see API keys):

client_id - Merchant key required for getting the access token.
client_secret - Merchant key required for getting the access token.
Ocp-Apim-Subscription-Key - The subscription key for making API requests.
merchantSerialNumber - The unique ID for your sales unit.
mobileNumber - The phone number for your test user.

No setup needed :)

Step 2 - Authentication

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 https://apitest.vipps.no/accessToken/get \
-H "client_id: YOUR-CLIENT-ID" \
-H "client_secret: YOUR-CLIENT-SECRET" \
-H "Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY" \
-H "Merchant-Serial-Number: 123456" \
-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" \
-X POST \
--data ''

The property access_token should be used for all other API requests in the Authorization header as the Bearer token.

Step 3 - A simple payment

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

curl
Postman

Send request Initiate Payment

curl --location 'https://apitest.vipps.no/ecomm/v2/payments/' \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni <truncated>" \
-H "Ocp-Apim-Subscription-Key: 0f14ebcab0ec4b29ae0cb90d91b4a84a" \
-H "Merchant-Serial-Number: 123456" \
-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" \
-X POST \
-d '{
  "customerInfo": {
    "mobileNumber": "91234567"
  },
  "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 - Completing 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 - Getting the status of the payment

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

curl
Postman

Send request Get Payment Details

curl https://apitest.vipps.no/ecomm/v2/payments/UNIQUE-PAYMENT-REFERENCE/details \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni <truncated>" \
-H "Ocp-Apim-Subscription-Key: 0f14ebcab0ec4b29ae0cb90d91b4a84a" \
-H "Merchant-Serial-Number: 123456" \
-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" \
-X GET

Step 6 - Capture the payment

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

curl
Postman

Send request Capture payment

curl https://apitest.vipps.no/ecomm/v2/payments/UNIQUE-PAYMENT-REFERENCE/capture \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni <truncated>" \
-H "Ocp-Apim-Subscription-Key: 0f14ebcab0ec4b29ae0cb90d91b4a84a" \
-H "Merchant-Serial-Number: 123456" \
-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" \
-H "X-Request-Id: 49ca711a-acee-4d01-993b-9487112e1def" \
-X POST \
-d '{
    "merchantInfo": {
        "merchantSerialNumber": "123456"
    },
    "transaction": {
        "transactionText": "This transaction was captured."
    }
}'

See Common topics: Capture for more details.

Optional steps

Refund the payment

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

curl
Postman

Send request Refund payment

curl https://apitest.vipps.no/ecomm/v2/payments/UNIQUE-PAYMENT-REFERENCE/refund \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni <truncated>" \
-H "Ocp-Apim-Subscription-Key: 0f14ebcab0ec4b29ae0cb90d91b4a84a" \
-H "Merchant-Serial-Number: 123456" \
-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" \
-H "X-Request-Id: 49ca711a-acee-4d01-993b-9487112e1def" \
-X POST \
-d '{
  "merchantInfo": {
        "merchantSerialNumber": "123456"
    },
    "transaction": {
        "transactionText":"This payment was refunded."
    }
}'

See Common topics: refund for more details.

Cancel the payment

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

curl
Postman

Send request Cancel payment

curl https://apitest.vipps.no/ecomm/v2/payments/UNIQUE-PAYMENT-REFERENCE/cancel \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni <truncated>" \
-H "Ocp-Apim-Subscription-Key: 0f14ebcab0ec4b29ae0cb90d91b4a84a" \
-H "Merchant-Serial-Number: 123456" \
-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" \
-X PUT \
-d '{
  "merchantInfo": {
        "merchantSerialNumber": "123456"
    },
    "transaction": {
        "transactionText":"This payment was cancelled."
    }
}'

See Common topics: 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.

Quick start

Before you begin​

Your first Payment​

Step 1 - Setup​

Step 2 - Authentication​

Step 3 - A simple payment​

Step 4 - Completing the payment​

Step 5 - Getting the status of the payment​

Step 6 - Capture the payment​

Optional steps​

Refund the payment​

Cancel the payment​

Next Steps​