> **Description:** Essential concepts and architecture of the ePayment API payment flows and lifecycle. # 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: Three-screen app-switch payment flow: (1) WebShop checkout with the app selected as payment method. (2) Payment app screen. (3) WebShop order confirmation page. 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](https://developer.vippsmobilepay.com/docs/knowledge-base/landing-page.md) 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](https://developer.vippsmobilepay.com/docs/recommended-flows/README.md) for several illustrated examples. A typical payment status follows these steps: Payment flow ```mermaid stateDiagram direction LR [*] --> Create Create --> Reserve: User confirms Reserve --> Capture: Merchant captures Capture --> [*] Capture --> Refund: Merchant refunds Refund --> [*] Reserve --> Cancel: Merchant cancels Create --> Cancel : User cancels, or timeout Cancel --> [*] ``` 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. ## 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 ``` ## Payment operations Each of these operations is described in this section. * [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) The [payment states](#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 ```mermaid stateDiagram-v2 direction TB %% Initial State [*] --> CREATED: Merchant creates a payment %% Transitions from CREATED CREATED --> AUTHORIZED: User confirms CREATED --> ABORTED: User cancels CREATED --> EXPIRED: User does nothing CREATED --> TERMINATED: Merchant cancels %% Final States AUTHORIZED --> [*] ABORTED --> [*] EXPIRED --> [*] TERMINATED --> [*] ``` Payment states: A payment starts as CREATED when the merchant creates it. From CREATED it can move to: AUTHORIZED (user confirms), ABORTED (user cancels), EXPIRED (user does nothing and the session times out), or TERMINATED (merchant cancels). All four are final states. Note: 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. 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 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). 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](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. | 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](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:/v1/payments/{reference}/events`](https://developer.vippsmobilepay.com/redocusaurus/epayment-swagger-id.yaml). Read about this more under [Get payment event log](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/operations/get_event_log.md). To track status in real-time, use both [Webhooks](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/webhooks.md) and polling [`GET:/epayment//v1/payments/{reference}`](https://developer.vippsmobilepay.com/redocusaurus/epayment-swagger-id.yaml), according to the [polling guidelines](https://developer.vippsmobilepay.com/docs/knowledge-base/polling-guidelines.md). The following diagram shows the *modification actions* for a payment. Payment actions ```mermaid stateDiagram-v2 direction TB [*] --> Create Create : Create Create : Merchant creates payment
request through API Create --> Authorize: User approves Create --> Abort: User cancels Create --> Expire: Session expires Create --> Terminate: Merchant cancels Authorize : Authorize Authorize : User approves payment Abort : Abort Abort : The user stops the payment
by tapping Cancel or similar Expire : Expire Expire : The payment session expires Terminate : Terminate Terminate : Merchant stops payment
through API Authorize --> [*] Abort --> [*] Expire --> [*] Terminate --> [*] ``` Payment states with descriptions: A payment starts at Create (merchant creates payment request through API). From Create it can move to: Authorize (user approves payment), Abort (user stops the payment by tapping Cancel or similar), Expire (the payment session expires), or Terminate (merchant stops payment through API). All four are terminal states. Modification actions after authorization ```mermaid stateDiagram-v2 direction TB Authorize: AUTHORIZED (final state) Authorize --> Capture: Merchant captures (full/partial) Capture --> Refund: Merchant refunds (full/partial) Refund --> [*]: Once payment is fully refunded Authorize --> Cancel: Merchant cancels uncaptured amount Capture --> Cancel: Not possible after full capture Cancel: Cancel Cancel --> [*] ``` Modification actions after authorization: From AUTHORIZED (final state), the merchant can capture the full or partial amount (moving to Capture), or cancel the uncaptured amount (moving to Cancel). From Capture, the merchant can refund the full or partial amount (moving to Refund). Once fully refunded, Refund is a terminal state. Cancellation after a full capture is not possible. ## 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 `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](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 [payment capture deadlines](https://developer.vippsmobilepay.com/docs/knowledge-base/reserve-and-capture.md#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](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-store payments](https://developer.vippsmobilepay.com/docs/recommended-flows/in-store/README.md) > **Full site overview:** For every page in this documentation, read [https://developer.vippsmobilepay.com/llms.txt](https://developer.vippsmobilepay.com/llms.txt).