Create payment
The first step in the payment flow is to create a payment with
POST:/epayment/v1/payments
.
This endpoint supports both wallet (i.e., the Vipps or MobilePay app) and
freestanding card payments, when card details are entered.
Each payment type offers separate user flows.
The paymentMethod.type
in the request determines the type of payment:
-
WALLET
: The user pays through the Vipps or MobilePay app. This includes delegated Secure Customer Authentication (SCA), where the login to the app eliminates the need for a separate SCA step.WALLET
payments include retry functionality such that, if the user attempts to pay with a declined card, they can retry with a different card for the same payment process. -
CARD
: The user pays with a card. They enter the card details into a form and then complete the 3D Secure step-up for SCA. See Card payments for more information.Please note: Card payment (
CARD
) is not available in the test environment.
General create request example
Here is an example HTTP POST:
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":6000
},
"customer":{
"phoneNumber":"4712345678"
},
"paymentMethod":{
"type":"WALLET"
},
"receipt":{
"orderLines": [
{
"name": "Socks",
"id": "line_item_1",
"totalAmount": 1000,
"totalAmountExcludingTax": 800,
"totalTaxAmount": 200,
"taxRate": 2550,
"unitInfo": {
"unitPrice": 400,
"quantity": "2.5",
"quantityUnit": "KG"
},
"discount": 0,
"productUrl": "https://example.com/store/socks",
"isReturn": false,
"isShipping": false
},
{
"name": "Flip-flops",
"id": "line_item_2",
"totalAmount": 5000,
"totalAmountExcludingTax": 4000,
"totalTaxAmount": 1000,
"taxRate": 2550,
"unitInfo": {
"unitPrice": 2500,
"quantity": "3",
"quantityUnit": "PCS"
},
"discount": 2500,
"productUrl": "https://example.com/store/flipflops",
"isReturn": false,
"isShipping": false
}
],
"bottomLine": {
"currency": "NOK",
"tipAmount": 0,
"posId": "pos_122",
"paymentSources": {
"giftCard": 0,
"card": 0,
"voucher": 0,
"cash": 0
},
"barcode": {
"format": "CODE 39",
"data": "SC0527013501"
},
"receiptNumber": "0527013501"
}
},
"reference":"acme-shop-123-1234589",
"paymentDescription": "Invoice# 424243, due date: 01 Jan 2025",
"returnUrl":"https://example.com/redirect?orderId=1512202",
"userFlow":"WEB_REDIRECT",
}'
The minimum amounts allowed are NOK 100 øre, DKK 1 øre, EUR 1 cent.
User flow alternatives
The userFlow
parameter specifies how the API should handle the payment
and how the user experience will be.
userFlow | Description |
---|---|
WEB_REDIRECT | The normal flow for browser-based payment flows. If on a mobile device, the Vipps or MobilePay app will open. Otherwise, the landing page will open. |
NATIVE_REDIRECT | Automatic app-switch between the merchant's native app and the Vipps or MobilePay app. |
PUSH_MESSAGE | For payments initiated on a device other than the user's phone, the user gets a push message that opens the payment in the app. This is similar to skipLandingPage . |
QR | Returns a QR code that can be scanned to complete the payment. |
WEB_REDIRECT
This is the default flow for wallet and card payments.
-
WALLET
flow: When the user is on a mobile device, redirect them to the Vipps or MobilePay app. From the desktop, open the landing page. -
Card
flow: Whether the user is on a desktop or mobile device, open the card entry page. See Card payments for more information.
NATIVE_REDIRECT
Applicable only for WALLET
payments.
The redirectUrl
will automatically open the Vipps or MobilePay app on mobile devices.
PUSH_MESSAGE
Applicable only for WALLET
payments.
For payments initiated on a device other than the user's phone. The user gets a push message that opens the payment in the app.
Using PUSH_MESSAGE
(and skipping the landing page) is only allowed when
it is not possible to show the landing page, when the payment is initiated on a device
that the user does not own or control. This includes:
- Not on the user's phone
- Not on the user's computer
- On a device that has no user-facing display where the landing page can be shown, such as physical points of sale (POS) solutions, vending machines, etc.
If userFlow
is PUSH_MESSAGE
, a valid customer
is required.
Please note: Sales units (i.e., Merchant Serial Numbers) must be especially approved to use this user flow. The merchant must have received the phone number from the customer with their consent for sending a payment request to the user's phone via Vipps or MobilePay app. To request this feature, please contact your key account manager, your partner manager, or customer service.
For more details, also see
skipLandingPage
.
QR
Applicable only for WALLET
payments.
This user flow is for customer-facing screens where payments can be initiated with the One-time payment QR.
Reference ID
The reference
field is used to identify a transaction.
The value must be unique for a sales unit (i.e., Merchant Serial Number).
Please read orderId / reference
for more recommendations.
Receipt
Add a receipt to the payment. This includes the order Lines for the payment, which are identical to those referenced in the Order Management API.
Applicable only for WALLET
payments.
Minimum user age
Set the minimum age required for the customer to make the purchase.
For example, make a
POST:/epayment/v1/payments
request with the following body:
{
"amount":{
"currency":"NOK",
"value":6000
},
"customer":{
"phoneNumber":"4712345678"
},
"minimumUserAge": 25,
"paymentMethod":{
"type":"WALLET"
},
"reference":"12345989434343",
"paymentDescription": "Something for older people",
"returnUrl":"https://example.com/redirect?reference=12345989434343",
"userFlow":"WEB_REDIRECT",
}
If the user owning the phone number is younger than the specified age (in years),
an error message will be provided.
In the WEB_REDIRECT
flow, the user enters their own phone number and sees the error message in the browser.
In the PUSH_MESSAGE
flow, the error is returned to you in the response.