> **Description:** Essential concepts and architecture of the ePayment API payment flows and lifecycle. > **AI agent:** Read [https://developer.vippsmobilepay.com/docs/knowledge-base/ai-tools.md](https://developer.vippsmobilepay.com/docs/knowledge-base/ai-tools.md) first. It covers keeping API keys and secrets out of generated code. > **Full site overview:** For an overview of the entire site, read [https://developer.vippsmobilepay.com/llms.txt](https://developer.vippsmobilepay.com/llms.txt). # 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. ## Brand requirements Following the [terms and conditions for Vipps MobilePay Business Solutions](https://vippsmobilepay.com/en-NO/terms-and-conditions): * Make Vipps MobilePay just as visible and easy to access as other payment methods, including digital wallets and payment apps. * Make Vipps MobilePay directly accessible, with no secondary menus or extra steps. * Show Vipps MobilePay at the same level as comparable payment methods. * Avoid consistently giving Vipps MobilePay a lower priority in the display or checkout flow. * Present Vipps MobilePay in a way that keeps checkout fair, easy to understand and quick to use. [See logos, text, and dos and don'ts for the checkout](https://brand.vippsmobilepay.com/document/61#/branding/online/branding-in-the-checkout) Use only the approved Vipps MobilePay buttons. The [Widget SDK](https://developer.vippsmobilepay.com/docs/knowledge-base/widget.md) is the recommended tool for starting the payment, because it shows the approved button and takes the customer to the payment for you: the app on a phone or tablet, or a dialog on a computer. It also keeps the button up to date when the brand changes. ## Authorization All ePayment API requests require an access token. Obtain one from the [Access Token API](https://developer.vippsmobilepay.com/docs/APIs/access-token-api/README.md) using [`POST:/accesstoken/get`](https://developer.vippsmobilepay.com/redocusaurus/access-token-swagger-id.yaml): ```bash 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 '' ``` In production, include all `Vipps-System` headers to aid debugging. See [HTTP headers](https://developer.vippsmobilepay.com/docs/knowledge-base/http-headers.md) for details. Use the returned `access_token` value as the Bearer token in the `Authorization` header of every subsequent API request: ```text Authorization: Bearer ``` ## Standard online payment 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. See [Online](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/features/online.md) for the steps, a request example, and the sequence diagram. The other [payment flows](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/features/README.md#payment-flows) change how the customer starts or approves the payment. In a physical store, you need to get the customer's phone number before creating the payment request. See [recommended flows](https://developer.vippsmobilepay.com/docs/recommended-flows/README.md) for several illustrated examples. ## Payment states A payment is acted on in two phases, divided by authorization. Up to that point the payment can still go either way: the user can approve or cancel it, the session can expire, or the merchant can terminate it through the API. Once the payment is authorized, the amount is reserved and the merchant can capture, refund, or cancel it. A typical payment status follows these steps: ```mermaid --- config: layout: elk elk: mergeEdges: false nodePlacementStrategy: LINEAR_SEGMENTS considerModelOrder: NODES_AND_EDGES --- flowchart LR START(( )) CREATE["Create"] RESERVE["Reserve"] CAPTURE["Capture"] REFUND["Refund"] CANCEL["Cancel"] END(( )) START --> CREATE CREATE -->|User confirms| RESERVE RESERVE -->|Merchant captures| CAPTURE CAPTURE --> END CAPTURE -->|Merchant refunds| REFUND REFUND --> END RESERVE -->|Merchant cancels| CANCEL CREATE -->|User cancels, or timeout| CANCEL CANCEL --> END ``` Payment lifecycle: A payment begins at Create. When the user confirms, it moves to Reserve. From Reserve, the merchant can capture the payment (moving to Capture) or cancel it (moving to Cancel). From Capture, the merchant can refund (moving to Refund). Refund and Cancel are terminal states. A payment can also move directly from Create to Cancel if the user cancels or a timeout occurs. A payment moves through several *states*. It changes state when the user or the merchant acts on it. Reaching authorization ```mermaid --- config: layout: elk elk: mergeEdges: false nodePlacementStrategy: NETWORK_SIMPLEX considerModelOrder: NODES_AND_EDGES --- flowchart TB START(( )) CREATED["CREATED
Merchant creates the payment
request through the API"] AUTHORIZED["AUTHORIZED ¹
User approves the payment"] ABORTED["ABORTED
The user stops the payment
by tapping Cancel or similar"] EXPIRED["EXPIRED
The payment session expires"] TERMINATED["TERMINATED
Merchant stops the payment
through the API"] START --> CREATED CREATED -->|User approves| AUTHORIZED CREATED -->|User cancels| ABORTED CREATED -->|Session expires| EXPIRED CREATED -->|Merchant cancels| TERMINATED ``` Payment states: a payment starts as CREATED when the merchant creates the request through the API. From CREATED it moves to one of four end states: AUTHORIZED if the user approves the payment, ABORTED if the user stops it by tapping Cancel or similar, EXPIRED if the payment session expires, or TERMINATED if the merchant stops it through the API. All four are final states, and even if the merchant captures, refunds, or cancels after authorization, the state remains AUTHORIZED. ¹ Even if the merchant (partially) captures, (partially) refunds, or cancels the payment, the state will remain AUTHORIZED. See [State reference](#state-reference) for what each state means, and [Payment modifications](#payment-modifications) for what the merchant can do after authorization. The payment operations are described in more detail on the following pages: * [Create payment](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/operations/create.md) * [Capture](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/operations/capture.md) * [Cancel](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/operations/cancel.md) * [Refund](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/operations/refund.md) ### Payment modifications The following modification actions can be made to `AUTHORIZED` payments: | State | Description | |--------------|--------------------------------------------------------| | [Capture](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/operations/capture.md) | The merchant captured part or all of an authorized payment. | | [Refund](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/operations/refund.md) | The merchant refunded part or all of an authorized payment. | | [Cancel](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/operations/cancel.md) | The merchant has cancelled the uncaptured amount of an authorized payment. | Capturing is time-limited. The reserved amount must be captured within the market-specific [capture attempt deadlines](https://developer.vippsmobilepay.com/docs/knowledge-base/reserve-and-capture.md#capture-attempt-deadlines). Refunding is also time-limited, as described in [General info: Refund payment](https://developer.vippsmobilepay.com/docs/knowledge-base/refund.md). Only an authorized payment has a reserved amount to work with. What the merchant can do with it depends on how much has already been captured. Modification actions after authorization ```mermaid --- config: layout: elk elk: mergeEdges: false nodePlacementStrategy: NETWORK_SIMPLEX considerModelOrder: NODES_AND_EDGES --- flowchart TB AUTHORIZED["Nothing captured
Full amount reserved"] PARTIAL["Partially captured
Remainder still reserved"] FULL["Fully captured
Nothing left to cancel"] RELEASED["Reservation released
Uncaptured amount
no longer available"] REFUNDED["Refunded
Captured amount
returned to the user"] AUTHORIZED -->|"Capture part"| PARTIAL AUTHORIZED -->|"Capture all"| FULL AUTHORIZED -->|"Cancel"| RELEASED PARTIAL -->|"Capture the rest"| FULL PARTIAL -->|"Cancel remainder"| RELEASED PARTIAL -->|"Refund captured part"| REFUNDED FULL -->|"Refund"| REFUNDED ``` The payment state stays `AUTHORIZED` throughout: none of these actions change it. Cancel is only possible while an uncaptured amount remains, so a fully captured payment cannot be cancelled. Modification actions after authorization, organized by how much of the reserved amount has been captured. With nothing captured yet, the merchant can capture part of the amount, capture all of it, or cancel to release the reservation. After a partial capture, the merchant can capture the rest, cancel the remaining uncaptured amount, or refund the part already captured. After a full capture, only a refund is possible, because no uncaptured amount is left to cancel. None of these actions change the payment state, which stays AUTHORIZED. To [get all the details about the payment](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/operations/get_info.md), including the captured and refunded amounts: Use [`GET:/epayment/v1/payments/{reference}`](https://developer.vippsmobilepay.com/redocusaurus/epayment-swagger-id.yaml), which will give you the `aggregate`. **TIP** You can see the history of the payment events with the [Get payment event log](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/operations/get_event_log.md) endpoint. To track status in real time, use both [Webhooks](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/webhooks.md) and polling [Get payment details](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/operations/get_info.md), according to the [polling guidelines](https://developer.vippsmobilepay.com/docs/knowledge-base/polling-guidelines.md). ### State reference 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, or cancelled, but it will not change the state. | ## Tracking the status Track status with both [Webhooks](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/webhooks.md) and polling, according to our [polling guidelines](https://developer.vippsmobilepay.com/docs/knowledge-base/polling-guidelines.md). Get the payment details with: * [Get payment details](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/operations/get_info.md) * [Get payment event log](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/operations/get_event_log.md) Learn about [ePayment webhooks](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/webhooks.md). ## 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](https://developer.vippsmobilepay.com/redocusaurus/epayment-swagger-id.yaml), the response will include an array of events, all with their respective `pspReference`. For example: ```json { ... "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](https://developer.vippsmobilepay.com/redocusaurus/epayment-swagger-id.yaml), [Cancel](https://developer.vippsmobilepay.com/redocusaurus/epayment-swagger-id.yaml), [Capture](https://developer.vippsmobilepay.com/redocusaurus/epayment-swagger-id.yaml), [Refund](https://developer.vippsmobilepay.com/redocusaurus/epayment-swagger-id.yaml)) return a `pspReference` in the response; this will match the CREATED event. So, this does not match the event log or the webhook. 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](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/errors.md#epayment-api-errors) * [Error handling: Rate limiting](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/errors.md#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 [capture attempt deadlines](https://developer.vippsmobilepay.com/docs/knowledge-base/reserve-and-capture.md#capture-attempt-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](https://developer.vippsmobilepay.com/docs/knowledge-base/reserve-and-capture.md#capture-regulations). If you do not plan to capture the entire amount, please make sure to [cancel](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/operations/cancel.md) 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](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/operations/cancel.md)). The [Electric vehicle charging flow](https://developer.vippsmobilepay.com/docs/recommended-flows/ev-charging/README.md) 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](https://developer.vippsmobilepay.com/docs/recommended-flows/online/README.md) * [In-person payments](https://developer.vippsmobilepay.com/docs/recommended-flows/in-store/README.md)