Quick start
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 test credentials from the merchant portal.
You will need the following values, as described in the Getting started guide:
client_id
- Client_id for a test sales unit.client_secret
- Client_id for a test sales unit.Ocp-Apim-Subscription-Key
- The subscription key for making API requests.merchantSerialNumber
- The unique ID for a test sales unit.mobileNumber
- The phone number for your test user.
- curl
- Postman
In Postman, import the following files:
π₯ To reduce risk of exposure, never store production keys in Postman or any similar tools. π₯
Update the Current Value field in your Postman environment with your Merchant Test keys. Use Current Value field for added security, as these values are not synced to the cloud.
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 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: 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" \
-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: 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" \
-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.
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: 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" \
-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: 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" \
-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: 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" \
-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: 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" \
-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.