Core concepts

This page gives you an overview of how payments work with Vipps MobilePay and guides you through each step of the general payment flow. Whether you're creating, capturing, cancelling, or refunding a payment, you'll find what you need right here. You'll also find links to important guidelines, error handling, and related topics to help you get up and running smoothly.

Basic flow

In your user interface, offer Vipps and/or MobilePay as a payment option. When the user selects their preferred method, send the payment request to us.
We'll then prompt the user in their Vipps or MobilePay app to complete the payment.

The basic online flow is:

Vipps

MobilePay

1. Customer selects to pay with Vipps or MobilePay
2. The merchant creates a payment request
3. The Vipps or MobilePay app will open with the request for payment.
   • If the customer is on a phone with the app installed, they get an automatic switch over to the Vipps/MobilePay app.
   • Otherwise, the Vipps/MobilePay landing page will open and they enter their phone number.
4. Customer confirms the payment in the app
5. The merchant's shop confirms the order
6. The merchant completes the order and shipping
7. The merchant captures the payment

In a physical store, you need to get the customer's phone number before creating the payment request. See recommended flows for several illustrated examples.

A typical payment status follows these steps:

Payment flow

Each of these operations are described in this section.

• Create payment
• Capture
• Cancel
• Refund

The payment states section explains how a payment changes state at each step.

Payment states

A payment can have several States. It can change states when a Modification is made.

This diagram shows all the states of a payment:

PAYMENT STATES

🚩 Even if the merchant (partially) captures, (partially) refunds, or cancels the payment, the state will remain AUTHORIZED.

When a payment is initiated, it has the state CREATED. Once a payment is confirmed by the user, the payment state is AUTHORIZED.

tip

You can see history of the payment events with the Get payment event log endpoint.

To track status in real-time, use both Webhooks and polling Get payment details, according to the polling guidelines.

Here is a description of each state:

State	Description	Example
CREATED	The payment has been initiated. The user has not yet acted upon the payment.	The user has received a push message, but not yet opened it. Or: The user has been sent to the landing page, but has not done anything in the app.
AUTHORIZED	The user has accepted the payment in the app. This is a final state.	The payment has been reserved, (partially) captured or (partially) refunded. A payment that has been captured (either fully or with one or more partial captures), or that has been refunded, will have one or more events, but the state would be AUTHORIZED.
ABORTED	The payment has been actively stopped by the user. The user has aborted the payment before authorization. This is a final state.	The user cancelled instead of accepting the payment.
EXPIRED	The payment has expired. The user did not act on the payment within the payment expiration time. This is a final state.	The user received a push message, but did nothing before the payment request timed out. By default, a user has a total of 10 minutes to accept a payment.
TERMINATED	The merchant has cancelled the payment before authorization. The merchant has terminated the payment via the cancel endpoint. This is a final state.	The merchant was not able to provide the product or service, and has cancelled the payment.
Other states	A payment will not change state after becoming AUTHORIZED. This is because a payment can be partially captured, and also partially refunded. It is therefore not practical to have states like "captured" or "refunded", since it is not possible to give all the information with just the state.	A payment can be partially captured, partially refunded, cancelled, but it will not change the state.

Payment modifications

The following modification actions can be made to AUTHORIZED payments:

State	Description
Capture	The merchant captured part or all of an authorized payment.
Refund	The merchant refunded part or all of an authorized payment.
Cancel	The merchant has cancelled the uncaptured amount of an authorized payment.

While you can capture, cancel and refund a payment after authorization, this does not change the state of the payment. A payment will remain in the state: AUTHORIZED.

To get all the details about the payment, including the captured and refunded amounts: Use GET:/epayment//v1/payments/{reference}, which will give you the aggregate.

tip

You can see history of the payment events with the GET:/v1/payments/{reference}/events. Read about this more under Get payment event log.

To track status in real-time, use both Webhooks and polling GET:/epayment//v1/payments/{reference}, according to the polling guidelines.

The following diagram shows the modification actions for a payment.

Payment actions

Tracking the status

Track status with both Webhooks and polling, according to our polling guidelines.

Get the payment details with:

• Get payment details
• Get payment event log

Learn about ePayment webhooks.

Understanding pspReference

The pspReference is a unique identifier defined by Vipps MobilePay. It can represent either a payment or an event, and every payment operation (e.g., capture, refund, or cancel) will have its own unique pspReference.

• Each event will have its own pspReference, serving as its unique identifier.

When you request Get a payment's event log, the response will include an array of events, all with their respective pspReference.

For example:

{
        ...
        "pspReference": "c70deb91-7684-451c-bac0-e433d66a6be5",
        "name": "CREATED",
        ...
    },
    {
        ...
        "pspReference": "10000568172",
        "name": "AUTHORIZED",
        ...
    },
    {
        ...
        "pspReference": "2267200447",
        "name": "CAPTURED",
        ...
    },
    {
        ...
        "pspReference": "2268200548",
        "name": "REFUNDED",
        ...
    }

You'll see that the pspReference is different for each entry.

note

The API requests (Get payment details, Cancel, Capture, Refund) return the pspReference provided in the response will match the CREATED event. So, this does not match the event log or the webhook.

The pspReference in webhook notifications

The webhooks always use the pspReference for the event. It aligns with the payment event log.

Error handling

For handling errors from the API, check out:

• Error handling: ePayment API errors
• Error handling: Rate limiting

Payment guidelines

You should capture as soon as is legally possible after a payment is reserved, because some banks will release the funds after some days, making it difficult to capture later. If it's not captured within the payment capture deadlines, it will be automatically cancelled.

However, be aware that it isn't legal to capture before the product or service is provided to the customer, as per the capture regulations.

If you do not plan to capture the entire amount, please make sure to cancel the remainder as soon as possible. Cancelling the remaining reservations will benefit the consumer, freeing up the amount for other purposes.

If you need to communicate some change to the payment after it has been reserved, you will need to send a new API request (e.g., cancel part of the amount).

The Electric vehicle charging flow shows an example of partially capturing the payment and then cancelling the remainder.

Related pages

See the many examples of online and in-store flows:

• Online payments
• In-store payments
• In-store using merchant callback QR
• Static QR directing to the app for payment