Skip to main content

Quick start

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.

Before you begin​

The Loyalty API is available in the production environment (https://api.vipps.no).

Pushing loyalty events​

Use the Loyalty API to push member data, coupons, stamp cards, and bonus checks into the Vipps MobilePay benefits tab.

Step 1 - Setup​

You must have already signed up as an organization with Vipps MobilePay.

The Loyalty API uses merchant-level keys: an API client that belongs to your organization rather than to a single sales unit, granted the loyalty-api:write scope. You need:

  • client_id - Client ID of your merchant-level API client.
  • client_secret - Client secret of your merchant-level API client. It is shown only once, when the client is created or the secret is rotated.

While the Loyalty API is in development, merchant-level keys for it are set up together with Vipps MobilePay. Contact your Vipps MobilePay contact person to get them.

You do not need an Ocp-Apim-Subscription-Key or a Merchant-Serial-Number. The access token identifies your organization.

The example values in this guide must be replaced with the values for your organization. This applies to API keys, HTTP headers, references, and similar values.

Step 2 - Get an access token​

All the API endpoints require that you first obtain an access token. Exchange your merchant-level keys for a token with Specialized authentication, a standard OAuth 2.0 client credentials flow against POST:/miami/v1/token.

Base64-encode client_id and client_secret together:

const clientId = 'YOUR-CLIENT-ID';
const clientSecret = 'YOUR-CLIENT-SECRET';
const base64Credentials = btoa(`${clientId}:${clientSecret}`);
console.log(base64Credentials);

Request a token with the loyalty-api:write scope:

curl -X POST https://api.vipps.no/miami/v1/token \
-H 'Authorization: Basic <YOUR-BASE64-ENCODED-VALUE>' \
-H 'Content-Type: application/x-www-form-urlencoded; charset=utf-8' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=loyalty-api:write'
Warning

You must include grant_type=client_credentials or you will get an invalid_client error. Do not send the Ocp-Apim-Subscription-Key header.

Example response:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzM4NCJ9 <truncated>",
  "token_type": "Bearer",
  "expires_in": 900
}

The token is valid for 15 minutes. Send it as Authorization: Bearer YOUR-ACCESS-TOKEN on every request. A token that is missing, expired, or lacks the loyalty-api:write scope is rejected with 401 not-authorized.

Step 3 - Register a member​

Send POST:/loyalty/v1/events with action: benefits.member.registered to add a new member to your loyalty program.

curl -X POST https://api.vipps.no/loyalty/v1/events \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
-H "Content-Type: application/json" \
-d '{
    "eventId": "evt-8a49f7b9-89cb-4e59-9db0-7f2f66a0a151",
    "timestamp": "2026-01-15T10:00:00Z",
    "action": "benefits.member.registered",
    "payload": {
      "contactId": "c1b0dcc3-9878-4079-92aa-f3c00cada3ea",
      "phoneNumber": "+4712345678",
      "joinedOn": "2026-01-15T10:00:00Z",
      "bonusPoints": {
        "balance": 0
      },
      "communicationPreferences": {
        "acceptsEmail": true,
        "acceptsSms": true,
        "acceptsPostal": false
      }
    }
  }'

A successful response confirms the event was accepted:

{
  "status": "accepted",
  "eventId": "evt-8a49f7b9-89cb-4e59-9db0-7f2f66a0a151"
}

Step 4 - Assign a coupon​

Send POST:/loyalty/v1/events with action: benefits.coupon.updated to assign a coupon to the member.

curl -X POST https://api.vipps.no/loyalty/v1/events \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
-H "Content-Type: application/json" \
-d '{
    "eventId": "evt-056850f5-86fd-476f-bdbd-e03e8dbf4461",
    "timestamp": "2026-03-01T09:00:00Z",
    "action": "benefits.coupon.updated",
    "payload": {
      "contactId": "c1b0dcc3-9878-4079-92aa-f3c00cada3ea",
      "phoneNumber": "+4712345678",
      "coupon": {
        "id": "promo-123",
        "parentId": "campaign-456",
        "heading": "20% off all jackets",
        "description": "Valid on all jackets in store and online",
        "expiresOn": "2026-06-30T23:59:59Z",
        "redeemed": false,
        "redemption": {
          "type": "online_and_in_store",
          "link": "https://merchant.com/campaign",
          "promotionCode": "JACKET20"
        }
      }
    }
  }'

Step 5 - Assign a stamp card​

Send POST:/loyalty/v1/events with action: benefits.stampCard.updated to assign a stamp card, and send the same action again every time the member collects a stamp. The usage values are absolute: timesUsed is the number of stamps collected so far and usesLeft is the number still needed for the reward.

curl -X POST https://api.vipps.no/loyalty/v1/events \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
-H "Content-Type: application/json" \
-d '{
    "eventId": "evt-9d6a5ad2-37fa-4a32-9ad3-b5e2c4fef1d7",
    "timestamp": "2026-03-05T14:20:00Z",
    "action": "benefits.stampCard.updated",
    "payload": {
      "contactId": "c1b0dcc3-9878-4079-92aa-f3c00cada3ea",
      "phoneNumber": "+4712345678",
      "stampCard": {
        "id": "stamp-789",
        "parentId": "stamp-campaign-1",
        "heading": "Buy 10 coffees, get 1 free",
        "description": "Collect a stamp on every coffee purchase.",
        "expiresOn": "2026-12-31T23:59:59Z",
        "redeemed": false,
        "usage": {
          "timesUsed": 7,
          "usesLeft": 3
        },
        "redemption": {
          "type": "in_store"
        }
      }
    }
  }'

When the member claims the reward, send benefits.stampCard.updated with redeemed: true or benefits.stampCard.deleted. Either removes the card from the benefits tab.

For the full list of supported actions and payload schemas, see the API guide.

Last updated on