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
- 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:/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 "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.
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 "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.