> **Description:** Step-by-step guide to implementing direct card payments in your web shop or merchant website using 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 ePayment works with freestanding cards

This is how card payments in web shops or merchant websites work with the ePayment API, where the customer pays
with a card instead of the Vipps or MobilePay app.

## Details

### 1. Customer selects their payment method

On the checkout page of a merchant's website or app, the customer chooses to pay with a card.

Screenshot: Mobile checkout payment method selection showing the app brand (Vipps or MobilePay) alongside Card as an alternative option.

### 2. The merchant creates a payment request

The merchant initiates a freestanding card payment with
[`POST:/epayment/v1/payments`](https://developer.vippsmobilepay.com/redocusaurus/epayment-swagger-id.yaml), specifying
`"paymentMethod": {"type": "CARD"}`, `"userFlow": "WEB_REDIRECT"`, and a `returnUrl`.

The response contains a `redirectUrl` pointing to the card entry page. Send the customer to that URL to start the
payment.

For a full example, see
[ePayment Features: Freestanding cards](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/features/freestanding-card-payments.md).

### 3. Customer enters card details

The card entry page opens, where the customer enters their card details and pays.

Screenshot: Card payment entry form with fields for card number, expiry date, and CVC, with a Pay button.

When the customer submits the card details, they are redirected back to the `returnUrl`.

**NOTE**

The card entry page is not currently available in the
[test environment](https://developer.vippsmobilepay.com/docs/knowledge-base/test-environment.md).

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

The merchant's system has no visibility into what happens on the card entry page, so it must subscribe to
webhooks to be notified when the customer acts on the payment. Register the webhook with the
[Webhooks API](https://developer.vippsmobilepay.com/docs/APIs/webhooks-api/api-guide.md) before creating the payment, so that no event is missed while
the customer is paying, and subscribe to all three outcomes:

* `epayments.payment.authorized.v1`: the customer completed the card payment.
* `epayments.payment.aborted.v1`: the customer canceled the payment.
* `epayments.payment.expired.v1`: the customer did not complete the payment in time, 10 minutes by default.

If the payment is aborted or expires, the order remains unpaid and the customer is returned to the checkout page,
where they can try again or select another payment method. Subscribing to `epayments.payment.authorized.v1` alone
leaves such orders waiting for a payment that will never arrive.

Webhooks can be delayed or missed, so do not rely on them alone. Back them up by polling
[`GET:/epayment/v1/payments/{reference}`](https://developer.vippsmobilepay.com/redocusaurus/epayment-swagger-id.yaml)
for the payment state, following the [polling guidelines](https://developer.vippsmobilepay.com/docs/knowledge-base/polling-guidelines.md):
start after 5 seconds, then check every 2 seconds.

### 5. The merchant's shop confirms the order

On successful payment, the merchant's store page or app opens, and the order is confirmed.

* If the payment was started on a mobile device, the store page or app will open again and confirm that the order was successful.
* If the payment was started on a desktop device, the customer can go back to the webpage, which confirms that the
  order was successful.

### 6. The merchant completes the order and shipping

The merchant completes the order and ships it to the customer.

### 7. The merchant captures the payment

Authorization only reserves the amount. Capturing the payment is what transfers the funds, so the merchant
captures once the order is ready to ship, using
[`POST:/epayment/v1/payments/{reference}/capture`](https://developer.vippsmobilepay.com/redocusaurus/epayment-swagger-id.yaml).

The funds are then transferred to the merchant's account. This may take 2 or 3 days, depending on the bank.

## Sequence diagram

Freestanding card payment flow

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

    C->>M: Select card as the payment method
    M->>ePayment: Initiate payment request with paymentMethod CARD
    ePayment-->>M: Return the redirectUrl to the card entry page
    M->>C: Send the customer to the card entry page

    C->>C: Enter the card details and pay
    Webhooks-->>M: Webhook: the payment was authorized, aborted, or expired
    M->>ePayment: Poll for payment info, as a backup if the webhook is delayed or missed
    ePayment-->>M: Current state of the payment
    alt The payment was aborted or expired
        M->>C: Return the customer to the checkout page
    else The payment was authorized
        M->>C: Display order confirmation
        M->>M: Prepare order (pack goods, ready to dispatch)
        M->>ePayment: Capture payment
        ePayment-->>M: Response with capturedAmount
        M->>M: Verify capturedAmount matches expected before shipping
        M->>C: Ship the order (only after full capture verified)
    end
```

  Customer selects card as the payment method.
  Merchant initiates a payment request via the ePayment API with the card payment method.
  ePayment API returns the redirect URL to the card entry page.
  Merchant sends the customer to the card entry page.
  Customer enters the card details and pays.
  Webhooks API sends the merchant an authorized, aborted, or expired event.
  Merchant 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 customer is returned to the checkout page and the flow
  ends.
  If the payment was authorized, the merchant displays order confirmation to the customer.
  Merchant prepares the order (packs goods, makes ready to dispatch).
  Merchant captures the payment via the ePayment API.
  ePayment API returns a response with the captured amount.
  Merchant verifies the captured amount matches expected before shipping.
  Merchant ships the order (only after full capture is verified).

## More details

For more details, see [ePayment Features: Accept freestanding card payments](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/features/freestanding-card-payments.md).