> **Description:** Visual walkthrough of the one-time payment QR flow for PSPs using card passthrough with the ePayment API.

> **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).

# How one-time payment QRs work for PSPs

This flow uses a one-time payment QR (a dynamic QR) shown on a screen, for PSPs using `CARD_PASSTHROUGH` with the
ePayment API.

Flow diagram: A one-time payment QR code displayed on a screen. The customer scans the QR
code with the Vipps or MobilePay app to authorize the payment.

The QR directs the customer to the Vipps or MobilePay app, where they select a
card and authorize the payment.

## Details

A [one-time payment QR code](https://developer.vippsmobilepay.com/docs/APIs/qr-api/api-guide/one-time-payment.md) is presented on the vending
machine or screen. The QR code is a dynamic representation of the payment URL, and the customer needs to scan it
and pay within 10 minutes.

### 1. The customer selects their products

The customer either scans their own products or hands them to an attendant.

### 2. The merchant's system requests a payment and dynamic QR code

When the customer selects a product, the system generates the payment request with a dynamic QR code by sending a
[`POST:/epayment/v1/payments`](https://developer.vippsmobilepay.com/redocusaurus/epayment-swagger-id.yaml) request with:

* `paymentMethod.type` set to `CARD_PASSTHROUGH`
* `userFlow` set to `QR` (optionally specify `qrFormat.format`, and `qrFormat.size` for PNG)
* `"customerInteraction": "CUSTOMER_PRESENT"` (required by regulation)
* [`psp`](https://developer.vippsmobilepay.com/docs/APIs/psp-epayment-api/epayment-psp-api-guide.md#psp) object with the PSP's server URL specified in
  the `callbackUrl` field
* [Other required parameters](https://developer.vippsmobilepay.com/docs/APIs/psp-epayment-api/epayment-psp-api-guide.md#parameters)

Since the customer scans the QR from their own phone, they don't need to supply a phone number.

For a full example, see [Create a QR payment](https://developer.vippsmobilepay.com/docs/APIs/psp-epayment-api/epayment-psp-api-guide.md#create-a-qr-payment).

### 3. Vipps MobilePay returns the QR code

Vipps MobilePay returns the one-time payment QR in the create payment response.

### 4. The merchant's system displays the QR on the screen

The merchant's system displays the one-time payment QR on a screen facing the customer.

### 5. The customer scans the QR and confirms the payment

The customer scans the QR code and is directed to the Vipps or MobilePay app, where they select a stored card and
confirm the payment. They have 10 minutes from when the QR is created.

### 6. The merchant learns the outcome from webhooks and polling

The merchant's system has no visibility into what happens in the app, so a webhook is how it learns that the
payment will not be completed:

* `epayments.payment.aborted.v1`: the customer canceled the payment in the app.
* `epayments.payment.expired.v1`: the customer did not confirm within 10 minutes.

On either event, the merchant's system removes the QR from the screen, releases the cart in the POS, and lets the
customer start over. No card callback follows, and the flow ends here.

Register the webhook before the QR is displayed, so no event is missed while the customer is paying. See
[Webhooks](https://developer.vippsmobilepay.com/docs/APIs/psp-epayment-api/epayment-psp-api-guide.md#webhooks) for what to register as a PSP and how to handle the events.

### 7. Vipps MobilePay sends the card token to the PSP

When the customer confirms the payment and selects their card, Vipps MobilePay sends a card token to the PSP's
`psp.callbackUrl`.

### 8. The PSP processes the payment and responds to the card callback

The PSP processes the payment through its own acquiring infrastructure using the card token, then responds to the
callback within 20 seconds. See [Card callback](https://developer.vippsmobilepay.com/docs/APIs/psp-epayment-api/epayment-psp-api-guide.md#card-callback) for the request
format, HMAC authentication, and expected response.

A `RESERVE` response reserves the amount for a later capture; it does not move the money. The payment is now
authorized, and the merchant's system can confirm this through the `epayments.payment.authorized.v1` webhook.

### 9. The PSP confirms the payment to the POS and to Vipps MobilePay

The PSP tells the merchant's system that the payment succeeded, so the POS can complete the sale and release the
goods to the customer.

The PSP captures the payment in its own systems. It then sends a capture request to the ePayment API, which does
not move any money; it only tells Vipps MobilePay to update the status so the customer sees the payment as
captured in their app.

Refunds and cancellations use the same endpoints, but happen later and only if something goes wrong. See
[Update payment status](https://developer.vippsmobilepay.com/docs/APIs/psp-epayment-api/epayment-psp-api-guide.md#update-payment-status).

## Sequence diagram

One-time payment QR flow for PSPs

```mermaid
sequenceDiagram
    autonumber
    actor C as Customer
    participant PSP as Merchant/PSP
    participant ePayment as ePayment API
    participant Webhooks as Webhooks API

    C->>PSP: Select the products
    PSP->>ePayment: Request a payment with CARD_PASSTHROUGH and userFlow QR
    ePayment-->>PSP: Return the one-time payment QR
    PSP->>C: Display the one-time QR on a screen facing the customer
    C->>C: Scan the QR, select a card, and confirm the payment
    Webhooks-->>PSP: Webhook: the payment was aborted or expired
    PSP->>ePayment: Poll for payment info, as a backup if the webhook is delayed or missed
    ePayment-->>PSP: Current state of the payment
    alt The payment was aborted or expired
        PSP->>PSP: Remove the QR and release the cart in the POS
    else The customer accepted the payment
        ePayment->>PSP: Card callback with the card token
        Note over PSP: Process the payment in its own acquiring systems
        PSP-->>ePayment: Respond to the callback with RESERVE within 20 seconds
        PSP->>PSP: Confirm the payment in the POS and complete the sale
        PSP->>ePayment: Send the capture status so the app shows it as captured
    end
```

  Customer selects their products.
  Merchant's system requests a payment via the ePayment API with card passthrough and a QR user flow.
  ePayment API returns the one-time payment QR to the merchant's system.
  Merchant's system displays the one-time QR on a screen facing the customer.
  Customer scans the QR, selects a card, and confirms the payment.
  Webhooks API sends the merchant's system an aborted or expired event if the customer does not accept the
  payment.
  Merchant's system gets the payment from the ePayment API, as a backup if the webhook is delayed or
  missed.
  ePayment API returns the current state of the payment.
  If the payment was aborted or expired, the merchant's system removes the QR and releases the cart in the
  POS, and the flow ends.
  If the customer accepts the payment, the ePayment API sends the card token to the PSP's card callback
  URL.
  PSP processes the payment in its own acquiring systems and responds to the callback with a reserve status
  within 20 seconds.
  PSP confirms the payment in the POS and completes the sale.
  PSP sends the capture status to the ePayment API, so the customer sees it as captured in the app.

## More information

* For technical details, see the [ePayment PSP API guide](https://developer.vippsmobilepay.com/docs/APIs/psp-epayment-api/epayment-psp-api-guide.md).
* For QR code generation options, see [ePayment Features: Payment through a QR](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/features/qr-payments.md).