Quick start
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.
The minimum amount in NOK and DKK is 100 ΓΈre. The minimum amount in EUR is 1 cent.
Your first Paymentβ
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_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.
You will also need:
internationalMobileNumber
- The MSISDN for the test app profile you have received or registered. This is your test mobile number including country code.
- curl
- Postman
π₯ 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:
-
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
internationalMobileNumber
No additional 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 -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: acme' \
-H 'Vipps-System-Version: 3.1.2' \
-H 'Vipps-System-Plugin-Name: acme-webshop' \
-H 'Vipps-System-Plugin-Version: 4.5.6' \
--data ''
Replace the value of the Vipps-System
headers with your own values.
See HTTP headers for more details.
When a partner uses
partner keys
for requests that are not for a specific merchant,
the Merchant-Serial-Number
can be omitted.
The property access_token
should be used for all other API requests in the Authorization
header as the Bearer token.
Step 3 - Request a simple 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
- Postman
Send request Create Payment - Web redirect
curl -X POST https://apitest.vipps.no/epayment/v1/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 '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 '{
"amount": {
"currency": "NOK",
"value": 1000
},
"paymentMethod": {
"type": "WALLET"
},
"customer": {
"phoneNumber": "4712345678"
},
"reference": "acme-shop-123-order123abc",
"returnUrl": "https://yourwebsite.come/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.
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
- Postman
Send request Get payment
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
- Postman
Send request Get payment event log
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
- Postman
Send request Capture payment
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
- Postman
Send request Refund payment
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
- Postman
Send request Cancel payment
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 '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" \
See Knowledge base: Cancel for more details about cancel.
Next Stepsβ
Now that you have completed your first payment, read further to see the full range of possibilities within the ePayment API.