Send payment invoices

💥 Work in progress 💥

Use Vipps to request payment from your customers for an invoice by combining requests for the ePayment and Order Management APIs.

This section will explain how to implement for different scenarios.

Customer's phone number is known

When the merchant has the customer's phone number and their approval to send a payment request through Vipps, they can send payment requests for invoices directly.

Please note:

The invoices should a link to a web view where the customer can get more details about the charges.
The invoices must be hosted by the merchant.

Start by adding a web view link to a payment by using the Order Management API.
Send the Add category to an order request. Note that the request path allows for different {paymentType} options. In this case, {paymentType} must be set to ecom. For example: https://api.vipps.no/v2/ecom/categories/{orderId}.
Here is an example of a valid request body:
```
{
"category": "GENERAL",
"orderDetailsUrl": "https://example.com/orderdetails/acme-shop-123-order123abc"
}
```

Make a create payment request.

Here is an example of a valid request body:

{
   "amount":{
      "currency":"NOK",
      "value":2000
   },
   "customer":{
      "phoneNumber":4791234567
   },
   "paymentMethod":{
      "type":"wallet"
   },
   "reference":"acme-shop-123-order123abc",
   "paymentDescription": "Invoice# 424243, due date: 01 Jan 2025",
   "returnUrl":"https://example.com/redirect?orderId=1512202",
   "userFlow":"PUSH_MESSAGE",
   "expiresAt":"2023-09-15T00:00:00Z"
}

For this solution, the following parameters must be set:

reference - The orderId used in Step 1.
expiresAt - The expiration date for the payment.
userFlow - Must be "PUSH_MESSAGE".
customer.phoneNumber - The customer's phone number.
paymentDescription - Short description with relevant information about the invoice.

The customer will receive a push notification in their Vipps app.
When the customer selects See details in the payment confirmation screen, they are presented with the order information provided by the merchant. In this scenario, they can tap this to view the invoice data hosted by the merchant in a web view without leaving the Vipps app.
The customer approves the payment.
For example, the sequence might look like this:
Invoice payments must have extended expiration dates, as specified in the create payment request.
Users can soft dismiss this payment by clicking Cancel -> I'll pay later and come back into the Vipps app to pay at a later time.
For more information about extended expiration dates, see Extended expiration for payments to merchants.

One time payment request

When a merchant does not know the phone number of the user and want to send a one-time request for payment for an invoice, they can use the Vipps API by following these steps.

In your website or mobile app or email you send, provide your customers with an option for opting-in to receive payment request for invoices in the Vipps app.
Present them with the Pay with Vipps option.
When they select Pay with Vipps, start by adding the invoice link to a web view, to a payment through the Order Management API.
Send the Add category to an order request. Note that the request path allows for different {paymentType} options. In this case, it must be set to ecom. For example: https://api.vipps.no/v2/ecom/categories/{orderId}.
Here is an example of a valid request body:
```
{
"category": "GENERAL",
"orderDetailsUrl": "https://example.com/orderdetails/acme-shop-123-order123abc"
}
```
Send the create payment request.
Request access to the user' phone number by including the scope parameter with a value of phoneNumber. In the paymentDescription field provide relevant information about the invoice.
Here is an example of a valid request body:
```
{
   "amount":{
      "currency":"NOK",
      "value":2000
   },
   "paymentMethod":{
      "type":"wallet"
   },
   "reference":"acme-shop-123-order123abc",
   "paymentDescription": "Invoice# 424242, due date: 31 Dec 2024",
   "returnUrl":"https://example.com/redirect?orderId=1512202",
   "userFlow":"WEB_REDIRECT"
}
```
For this solution, the following parameters must be set:
- reference - The orderId used in Step 3.
- paymentDescription - Short description with relevant information about the invoice.
If the customer is on a desktop computer, the Vipps Landing page opens. If on a mobile device, the Vipps app opens.
The customer approves the payment in the Vipps app.
These steps can be visualized as:

Customer's phone number is not known

When a merchant does not know the phone number of the user, they can request payment through the Vipps APIs by following these steps.

In your website or mobile app or email you send, provide your customers with an option for opting-in to receive payment request for invoices in the Vipps app.
They view their invoice in your website or app.
Present them also with the Pay with Vipps option.

When they select Pay with Vipps, send the create payment request.

Request access to the user' phone number by including the scope parameter with a value of phoneNumber. In the paymentDescription field provide relevant information about the invoice.

Here is an example of a valid request body:

{
   "amount":{
      "currency":"NOK",
      "value":2000
   },
   "customer":{
      "phoneNumber":4791234567
   },
   "paymentMethod":{
      "type":"wallet"
   },
   "profile":{
      "scope":"phoneNumber"
   },
   "reference":"acme-shop-123-order123abc",
   "paymentDescription": "Invoice# 424242, due date: 31 Dec 2024",
   "returnUrl":"https://example.com/redirect?orderId=1512202",
   "userFlow":"WEB_REDIRECT"
}

If the customer is on a desktop computer, the Vipps Landing page opens. If on a mobile device, the Vipps app opens.
The customer consents to share their phone number.
The customer approves the payment in the Vipps app.
These steps can be visualized as:
To retrieve the user's phone number, start by making a request to Get Payment to get the sub value.
Then, make a request to getUserinfo. For details and more examples, see the UserInfo API.
Finally, use the customer's phone number to send them direct payment requests in the future.

Send payment invoices

Customer's phone number is known​

One time payment request​

Customer's phone number is not known​

Customer's phone number is known

One time payment request

Customer's phone number is not known