Skip to main content

Migration from the eCom API to the ePayment API

note

We recommend using Checkout when accepting payments online. With Checkout, you'll get Vipps/MobilePay, VISA, and MasterCard payments nicely packaged with customer information retrieval and shipping selection. Try it out yourself or see the documentation.

The ePayment API expands upon the functionality of the eCom API and simplifies the existing flows. Merchants currently using the eCom API should find the ePayment API familiar and intuitive.

The ePayment API is backwards compatible with the eCom API. This means that payments initiated via the eCom API can be captured, refunded, cancelled, and retrieved using the ePayment API.

note

The ePayment API is backwards compatible with the eCom API. However, the eCom API is not forwards compatible with the ePayment API. This means that payments initiated with the ePayment API can't be modified or retrieved using the eCom API.

Merchants are advised to fully migrate over to the ePayment API. However, it is possible to migrate one endpoint at a time, provided that the Create Payment endpoint is migrated last (see above note).

See Can payments be "mixed and matched" between the eCom API and the ePayment API?

Important: The ePayment API only offers “reserve capture”. There is no “direct capture”, as in the eCom API. Read more about the benefits of "reserve capture": Reserve and capture.

Callbacks

Unlike the eCom API payment callbacks, the ePayment API does not use the callbackPrefix as part of the Initiate Payment request. Instead, you can use the Webhooks API to register URLs that will receive a webhook (a POST request) whenever various events occur for your payments.

info

Please note: The Webhooks API provides guaranteed delivery: If the callback is not successful (we do not get the expected response from you), we will retry sending it for several days. In addition, you can now receive callbacks for all adjustments to your payment.

Payment flows

In the eCom API, merchants could choose between three flows by specifying the parameters isApp and skipLandingPage, as described in Knowledge base: Deep link flow.

These parameters were added to the original API over the years. The same functionality is available in ePayment, but smarter: Instead of specifying the parameters, you now simply decide which flow you want through the userFlow property. Here's how the fields correspond to each other:

  • isApp: false and skipLandingPage: false -> WEB_REDIRECT
  • isApp: true and skipLandingPage: false -> NATIVE_REDIRECT
  • skipLandingPage: true -> PUSH_MESSAGE

The ePayment API also supports a new flow: the QR flow. The QR flow provides you with a direct link to a one-time payment QR code that the user can scan and pay from their app.

Renamed and altered fields

  • fallBack -> Renamed returnUrl
  • scope -> Moved inside the profile object
  • transactionText -> Renamed paymentDescription
  • orderId -> Renamed reference
  • phoneNumber: Now requires the MSISDN format, where the country code is included. See the API specification, and MSISDN.

Report API and settlements

The eCom API and ePayment API use different identification for payments:

  • eCom API payments are identified with the orderId that is specified when the payment is initiated.
  • ePayment API payments are identified with the reference in the same way.

When retrieving data about the payments using the Report API there is also a difference:

  • eCom API payments will have an automatically generated transactionId for each payment operation, such as capture, refund, etc.
  • ePayment API payments will have a pspReference that works similarly.
info

The transactionId in the eCom API is identical to the pspReference in the Report API, but the pspReference in the ePayment API has no relation to the pspReference in the Report API.

See the Report API's Entry type reference fore more details.

Payment Method

The ePayment API supports freestanding card payments. Merchants are required to provide a value to the paymentMethod field to specify if card payments should be used.

note

The WALLET payment method means the user will use the Vipps app to pay. The CARD payment method is intended for users who are not able to (or don't want to) use the app to pay.

Express Payments

See: Is Express Checkout available in the ePayment API?

Partial Cancellations

Cancellation of partially captured payments is supported in the eCom API by setting the shouldReleaseRemainingFunds flag in the PUT:/ecomm/v2/payments/{orderId}/cancel request.

In the ePayment API, this behavior is the default behavior for the POST:/epayment/v1/payments/{reference}/cancel request, and there is no need to do anything extra.

Customer Present Payments

See Customer-Present Payments.

Help us improve our documentation

Did you find what you were looking for?