Skip to main content

Migrating from Checkout V2 to V3

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

Give your assistant up-to-date guidance for our APIs, with our plugin or without it.

The plugin is still under development. See the AI tools page for details.

Run both commands, in order.

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

For troubleshooting, see the full instructions.

Important update

Vipps MobilePay has entered into an agreement to sell the Checkout solution to Kustom.

As part of this transition, Vipps MobilePay Checkout will become Kustom Checkout. This means the Checkout product you ordered will be delivered and developed by Kustom going forward. If you have questions, you can check our FAQ.

Checkout V3 improves upon V2 through alignment of polling and callback responses, improvement of field names, and expansion of models related to logistics options to permit more advanced features. This guide takes you through the things you need to change in your existing V2 integration to support Checkout V3.

Initiate session​

CheckoutConfiguration​

The field Configuration has been added to InitiateSessionRequest and the following fields have been moved into it:

  • customerInteraction
  • userFlow
  • requireUserInfo
  • elements

The elements field replaces the former ContactFields and AddressFields flags with an enum. They are equivalent according to the following table.

ElementsContactFieldsAddressFields
Full (default)truetrue
PaymentAndContactInfotruefalse
PaymentOnlyfalsefalse

We have also added a new Countries field which allows merchants to specify which countries they support.

CallbackUrl​

callbackUrlPrefix has been replaced by callbackUrl so that you send in the whole URL to where you want the "Payment Completed" callback.

Strongly typed fields​

The following are now strongly typed:

  • customerInteraction
  • userFlow

The permitted values for these fields used to be case-insensitive. They are now case-sensitive.

Logistics​

The logisticsOption object is now changed to better accommodate more advanced Checkout features. It is now a polymorphic object whose type is determined by which logistics carrier is used. Refer to Swagger for more details.

Polling and callback​

The response object from polling and the callback object are now identical.

UserDetails​

userDetails has been removed. If requireUserInfo is set to true in session initiation, user info will instead be provided in its own dedicated response object UserInfo.

"userInfo": {
    "sub": string,
    "email": string
}

PaymentDetails​

paymentDetails.State is now Authorized with a z instead of Authorised with an s.

Renaming of region to city​

billingDetails.region has been renamed to billingDetails.city. shippingDetails.region has been renamed to shippingDetails.city.

Standardized country name​

billingDetails.country and shippingDetails.country were previously derived from the free-text field filled in by the customer. We have now changed this to always be two-letter codes that adhere to the ISO-3166-1 Alpha-2 standard.

Cancel session​

The endpoint for canceling sessions has been removed for V3.

To make changes or updates to a session, initiate a new session with the same reference as the previous one. This will automatically cancel the previous session. However, if the customer has initiated the payment by clicking "Complete Purchase" in the checkout window, replacing the Checkout session will not work. In such cases, you can cancel the payment through the ePayment API.

Last updated on