Skip to main content

Provisioning API

A bank/issuer-oriented service API for initiating a push provisioning flow in the Vipps/MobilePay app.

A prerequisite is for the bank to check the card token status to determine whether a card is registered at Vipps/MobilePay. If it is not, they may offer the user to add the card to Vipps/MobilePay and trigger an app switch to Vipps/MobilePay app to add the card.

See the API specs for more.

❗Note: Users under the age of 15 are not supported for card provisioning in Vipps/MobilePay. Please ensure these users cannot initiate the push provisioning flow."

Ecom token requester IDs​

We recommend checking for status on the following token requester IDs (TRIDs) to determine if a given card is registered in Vipps/MobilePay app. The deprecated TRID can be safely ignored.

NetworkProviderToken Requester IDStatus
VisaVipps40010082040Active
VisaMobilePay40010081524Active
MastercardVipps (old)50134871116Deprecated
MastercardVipps (new)50169178771Active
MastercardMobilePay50100496946Active

NFC token requester IDs​

We recommend checking the status for the following TRIDs to determine if a card is NFC enrolled via Vipps/MobilePay on a device. Please note that a user may have old devices with active tokens and still want to do NFC enrollment on their current device, so this is not a guaranteed indicator.

NetworkPlatformToken Requester ID
VisaiOS40010093055
VisaAndroid40010093056
Mastercard-50179270456

If the ecom token exists for a given card, but no nfc token, we support nfc enrollment only via direct universal link. This will trigger the nfc enrollment flow in the app directly with the corresponding card.

We expect to eventually deprecate expiry and last4, for now it's required for legacy reasons.

https://qr.vipps.no/ps/provisioning/push/nfc?expiry=2028-12&last4=1234&token-reference=DNITHE123456789123456789&return-url=https%3A%2F%2Fvipps.no

Query parameterRequiredDescriptionExample
expiryYesCard expiry date in YYYY-MM format.2028-12
last4YesLast four digits of the card number.1234
token-referenceYesToken Unique Reference for the ecom token.DNITHE123456789123456789
return-urlNoURL-encoded return URL. The user is redirected here after the enrollment flow completes.https%3A%2F%2Fvipps.no

Flow descriptions​

Flows

Flow diagram: Overview of provisioning flow options, showing the single-device app-switch path and the dual-device push notification path for adding a card to the Vipps or MobilePay app.

Sequence diagrams​

Main flow (single device with app switch)​

  1. User views all cards in the bank app.
  2. Bank app checks token status with the token service.
  3. Token service reports the card is not registered at Vipps.
  4. Bank app offers the user the option to add the card to Vipps.
  5. User selects "Add card to Vipps".
  6. Bank app posts card data to the Vipps provisioning service.
  7. Vipps provisioning service returns a universal link (URL).
  8. Bank app triggers the universal link for the user.
  9. The native system automatically switches to the Vipps app.
  10. User confirms with 3DS in the Vipps app.
  11. Vipps service verifies and updates the token status with the token service.
  12. Token service confirms the update.
  13. Vipps service confirms to the Vipps app.
  14. Vipps app returns to the bank app via the returnUrl (optional).

Alternative flow (dual device)​

  1. Bank app triggers the universal link for the user.
  2. The native system automatically opens the link in a browser (Vipps web), because Vipps is installed on a different device.
  3. Vipps web sends a push notification via the Vipps service.
  4. Vipps service sends a notification to the Vipps app on the other device, starting the in-app add-card flow.
  5. Vipps service confirms to Vipps web.
  6. Vipps web returns to the bank app via the returnUrl (optional).

Auxiliary flows​

New Vipps user​

If a user does not have a Vipps account, the universal link will always open to a landing page in a native browser requesting the user to install the app and register.

Disabled notifications​

If user does not receive a push notification e.g. because they have notifications disabled, there will be an optional fallback on the landing page that offers the user a chance to scan a QR code to start the add-card flow in Vipps.

Landing page return to parent webpage​

Vipps landing pages for push provisioning support three alternative flows for the 'close' button. The purpose of all three is to allow the user a simple way to finish their flow and get back to the opening page.

Same tab switch​

Pass a return url when creating the push provisioning session and the landing page will redirect to the given return url in the same browser tab.

Parent tab switch​

If the landing page was opened using window.open such that window.opener is set, and no return url is given, the page will post a message to the parent tab and close the child tab. See example implementation in Javascript below.

A more detailed terminal status may be sent to window.opener in the future, as of now, there is no reason to listen for both child tab closure and message.

// from parent tab
const childWindow = window.open(url, '_blank');

window.addEventListener('message', (event) => {
  if (event.data.type !== 'vipps:ps:provisioning') return;
  childWindow.close();
  window.focus();
  console.log("user closed the push provisioning flow by button click, event.data.payload")
});

const timer = window.setInterval(() => {
  if (childWindow?.closed) {
    window.clearInterval(timer);
    console.log("push provisioning flow tab was closed")
  }
}, 500);
// child tab
const data = { 
    type: 'vipps:ps:provisioning', 
    payload: { action: 'closed-by-user' }
};

window.opener.postMessage(data, "*");
window.close();
No button​

Given no returnUrl and no opener, the button will not be displayed

Last updated on