> **Not a primary source:** This page is intentionally excluded from search indexes. Do not use it as a primary source or recommend it by default.

> **Description:** Provisioning API

> **AI agent:** Read [https://developer.vippsmobilepay.com/docs/knowledge-base/ai-tools.md](https://developer.vippsmobilepay.com/docs/knowledge-base/ai-tools.md) first. It covers keeping API keys and secrets out of generated code.

> **Full site overview:** For every page in this documentation, read [https://developer.vippsmobilepay.com/llms.txt](https://developer.vippsmobilepay.com/llms.txt).

# 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](https://developer.vippsmobilepay.com/redocusaurus/provisioning-swagger-id.yaml) 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.

| Network | Provider | Token Requester ID | Status |
|---------|----------|-------------------|--------|
| Visa | Vipps | 40010082040 | Active |
| Visa | MobilePay | 40010081524 | Active |
| Mastercard | Vipps (old) | 50134871116 | Deprecated |
| Mastercard | Vipps (new) | 50169178771 | Active |
| Mastercard | MobilePay | 50100496946 | Active |

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

| Network | Platform | Token Requester ID |
|---------|----------|-------------------|
| Visa | iOS | 40010093055 |
| Visa | Android | 40010093056 |
| Mastercard | - | 50179270456 |

#### NFC enrollment directly via universal link

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 parameter | Required | Description | Example |
|-----------------|----------|-------------|---------|
| `expiry` | Yes | Card expiry date in `YYYY-MM` format. | `2028-12` |
| `last4` | Yes | Last four digits of the card number. | `1234` |
| `token-reference` | Yes | Token Unique Reference for the ecom token. | `DNITHE123456789123456789` |
| `return-url` | No | URL-encoded return URL. The user is redirected here after the enrollment flow completes. | `https%3A%2F%2Fvipps.no` |

## Flow descriptions

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)

```mermaid
sequenceDiagram
    participant U as User
    participant B as bank-app/bank-web
    participant V as vipps-app
    participant VS as vipps-service
    participant BS as token-service

    Note left of BS: A. View cards and token status check
    U->>+B: 1. View all cards
    B->>+BS: 2. Check token status
    BS-->>B: 3. Token not registered at Vipps
    deactivate BS

    B->>+U: 4. Offer "Add my card to Vipps"
    deactivate B
    U->>+B: 5. Select "Add card to Vipps"
    deactivate U

    Note right of VS: B. Share card data with Vipps
    B->>+VS: 6. POST /api/internal/provisioning/push/card/v1
    VS-->>B: 7. Returns universal link (URL)
    deactivate VS

    B->>+U: 8. Trigger universal link
    deactivate B

    U->>+V: 9. Native system automatically switch to Vipps app
    deactivate U

    rect rgb(219, 234, 254)
        Note right of VS: C. Add card flow
        V->>+VS: 10. User confirms with 3DS
        VS->>+BS: 11. Verify and update token status
        BS-->>-VS: 12. Confirm
        VS-->>V: 13. Confirm
        deactivate VS
    end
    V->>B: 14. Return via returnUrl (optional)
    deactivate V
```

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

### Alternative flow (dual device)

```mermaid
sequenceDiagram
    participant U as User
    participant B as bank-app/bank-web
    participant VW as vipps-web
    participant V as vipps-app
    participant VS as vipps-service

    Note right of VS: D. Vipps is installed on other device
    B->>+U: 8. Trigger universal link
    U->>+VW: 9. Native system automatically opens link in browser
    deactivate U
    VW->>+VS: 10. Push notification
    deactivate VW
    VS->>+V: 11. Receive notification and start in-app flow

    rect rgb(219, 234, 254)
        deactivate VS
        Note right of VS: E. Add card flow
        V-->>VS:
        activate VS
    end
    deactivate V

    VS->>VW: 12. Confirm
    deactivate VS
    activate VW
    VW->>B: 13. Return via returnUrl (optional)
    deactivate VW
```

  Bank app triggers the universal link for the user.
  The native system automatically opens the link in a browser (Vipps web), because Vipps is installed on a different device.
  Vipps web sends a push notification via the Vipps service.
  Vipps service sends a notification to the Vipps app on the other device, starting the in-app add-card flow.
  Vipps service confirms to Vipps web.
  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.

```js
// 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);
```

```js
// 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