Vipps Playbook
Step-by-step guide for configuring, testing, and maintaining Vipps MobilePay in BISO Sites.
Vipps Playbook
Use this guide whenever you onboard a new Vipps account, rotate credentials, or troubleshoot payments. Keep it close to the finance lead so you can hand over responsibility quickly.
When to follow this guide
- New IT manager setting up payments for the first time
- Rotating or revoking credentials (every 6–12 months)
- Investigating failed checkouts or webhook issues
- Auditing the payment flow before large events
Account setup
Access the Vipps Developer Portal
Go to portal.vipps.no and confirm you have admin rights for the student union account.
Register test + production apps
Create one app for Sandbox and one for Production. Record their IDs in the shared password vault along with a note about the owner.
Enable MobilePay Checkout
In each app, enable the Checkout scope and configure the callback URL (/api/payment/vipps/callback) and return URL (/checkout/return).
Share credentials securely
Store the client ID, client secret, merchant serial number, and subscription key in the vault. Never paste them into Slack or email.
Credentials & environment variables
VIPPS_CLIENT_ID– from the developer portal (test app).VIPPS_CLIENT_SECRET– client secret for the test app.VIPPS_SUBSCRIPTION_KEY– test subscription key.VIPPS_MERCHANT_SERIAL_NUMBER– test merchant number.VIPPS_TEST_MODE=true(required).NEXT_PUBLIC_BASE_URL– where Vipps should send users back (usually `http://localhost:3000`).
Whenever you rotate credentials, immediately update all three .env.local files, Vercel/Docker secrets, and the shared vault entry. Out-of-sync values are the #1 cause of failed payments.
Test a transaction
Switch to sandbox
Set VIPPS_TEST_MODE=true and use the sandbox credentials. Restart the dev server.
Place an order
In the web app shop, add a product and check out. Use the Vipps test number provided in the portal.
Verify order status
In Appwrite, confirm the orders document transitions from PENDING → PAID. Also check the admin dashboard for the updated status.
Review logs
Look at the server logs (bun run dev --filter=web) and the Vipps portal event log to ensure the webhook fired successfully.
Troubleshooting
- User stuck on Vipps redirect – Confirm the callback URL matches the deployed domain and that HTTPS certificates are valid.
- Order never updates – Check Appwrite logs and ensure the API key used in
handleVippsCallbackstill hasdatabasesscope. Unauthorizedresponse from Vipps – Credentials are invalid or expired; rotate them in the portal and redeploy.- Currency mismatch – Vipps only supports NOK for this integration. Ensure prices and totals are in NOK.
Escalation checklist
- Capture the order ID, Vipps transaction ID, and timestamp.
- Download logs from
/api/payment/vipps/callbackand the Vipps portal. - Contact Vipps support using the merchant ID and attach the logs.
- Update this document with the resolution so the next maintainer learns from it.