Skip to main content

How ePayment works with freestanding cards

View as Markdown (opens in a new tab)
Install AI tools

Our plugin gives your assistant up-to-date guidance for payments and login. Full instructions

Run both commands, in order.

claude plugin marketplace add vippsas/agent-toolkit
claude plugin install vipps@agent-toolkit

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.

Pay with Card or Vipps

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, 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.

3. Customer enters card details​

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

Enter card details

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.

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 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} for the payment state, following the polling guidelines: 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.

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

100%
  1. Customer selects card as the payment method.
  2. Merchant initiates a payment request via the ePayment API with the card payment method.
  3. ePayment API returns the redirect URL to the card entry page.
  4. Merchant sends the customer to the card entry page.
  5. Customer enters the card details and pays.
  6. Webhooks API sends the merchant an authorized, aborted, or expired event.
  7. Merchant gets the payment from the ePayment API, as a backup if the webhook is delayed or missed.
  8. ePayment API returns the current state of the payment.
  9. If the payment was aborted or expired, the customer is returned to the checkout page and the flow ends.
  10. If the payment was authorized, the merchant displays order confirmation to the customer.
  11. Merchant prepares the order (packs goods, makes ready to dispatch).
  12. Merchant captures the payment via the ePayment API.
  13. ePayment API returns a response with the captured amount.
  14. Merchant verifies the captured amount matches expected before shipping.
  15. Merchant ships the order (only after full capture is verified).

More details​

For more details, see ePayment Features: Accept freestanding card payments.

Last updated on