Skip to main content

Quick start

This guide takes you through all the ePayment API requests.

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​

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 international mobile number. 🔥 Do not store production keys in the cloud. 🔥

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 -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:/epayment/v1/payments. In this example, we use the default user flow, WEB_REDIRECT. This provides you with a link you can click to go to the landing page. When your test mobile number (in MSISDN format) is provided in phoneNumber, it will be prefilled in the form.

curl -X POST https://apitest.vipps.no/epayment/v1/payments \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
-H "Idempotency-Key: YOU-CREATE-YOUR-IDEMPOTENCY-KEYS" \
-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 '{
"amount": {
"currency": "NOK",
"value": 1000
},
"paymentMethod": {
"type": "WALLET"
},
"customer": {
"phoneNumber": "4712345678"
},
"reference": "acme-shop-123-order123abc",
"returnUrl": "https://yourwebsite.com/redirect?reference=abcc123",
"userFlow": "WEB_REDIRECT",
"paymentDescription": "One pair of socks"
}'

Step 4 - Complete the payment​

Open the redirectUrl link that is returned, 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 the payment and be directed to the specified returnUrl 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:/epayment/v1/payments/{reference}.

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

To verify that a payment has been authorized by the user, check that the state property is marked AUTHORIZED. If the user has instead chosen to reject the payment or chosen to click cancel on the landing page or in the app, the state property will be marked ABORTED. If the user did not act within the payment expiration time, the state property will be marked EXPIRED.

For more details of the lifecycle of the payment session the GET:/epayment/v1/payments/{reference}/events endpoint.

curl -X GET https://apitest.vipps.no/epayment/v1/payments/UNIQUE-PAYMENT-REFERENCE/events \
-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:/epayment/v1/payments/{reference}/capture.

curl -X POST https://apitest.vipps.no/epayment/v1/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 'Idempotency-Key: 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 '{
"modificationAmount": {
"currency": "NOK",
"value": 1000
}
}'

See Knowledge base: Reserve and capture for more details about the types of captures.

Step 7 - Refund the payment​

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

curl -X POST https://apitest.vipps.no/epayment/v1/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 'Idempotency-Key: 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 '{
"modificationAmount": {
"currency": "NOK",
"value": 1000
}
}'

See Knowledge base: refund for more details about refunds.

Step 8 - Cancel the payment​

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

curl -X POST https://apitest.vipps.no/epayment/v1/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" \

See Knowledge base: Cancel for more details about cancel.

Next Steps​

Complete the required ePayment checklist to integrate the API into your software.

Checklist lady

Help us improve our documentation

Did you find what you were looking for?