Migration from the eCom API to the ePayment API
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.
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.
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
andskipLandingPage: false
->WEB_REDIRECT
isApp: true
andskipLandingPage: 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
-> RenamedreturnUrl
scope
-> Moved inside theprofile
objecttransactionText
-> RenamedpaymentDescription
orderId
-> Renamedreference
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.
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.
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.