Skip to main content

How agreement sign-up works for PSPs

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.

A step-by-step walkthrough of a subscription agreement sign-up using card passthrough, from the merchant's website to the active agreement.

Details​

Vipps fixed price agreement

Screenshot: Payment agreement sign-up flow — screen 1: merchant website shows a "Premium subscription" with a Pay with Vipps button; screen 2: the app (Vipps or MobilePay) displays an "Agreement with" the merchant showing the product name, frequency, and a "Notify me when paying" toggle, with a Next button; screen 3: the same agreement screen with a payment method confirmation sheet showing the selected card and a Confirm button; screen 4: the merchant website shows an order confirmation with a summary of the Premium subscription.

1. Customer selects a subscription​

On the merchant's website or app, the customer chooses to subscribe and pay with Vipps or MobilePay.

2. The PSP drafts an agreement​

The PSP drafts an agreement with POST:/recurring/v3/agreements, including the cardPassthrough object with a cardCallbackUrl. An optional initialCharge sets the upfront payment amount — if omitted, a zero-amount verification is performed instead. See Agreement sign-up for the full request details.

The request must include the Merchant-Serial-Number header for the merchant/sales unit the PSP is operating on behalf of. Use the merchant's MSN, not the PSP's own MSN.

3. Customer opens the Vipps or MobilePay app​

If the agreement was initiated on a mobile device, the Vipps or MobilePay app opens automatically.

If initiated on a desktop device, the landing page opens. The customer enters their phone number and the agreement request is sent to their phone.

4. Customer selects a card and approves the agreement​

The customer reviews the agreement terms, selects a card stored in their Vipps or MobilePay app, and confirms.

5. Vipps MobilePay sends the card token to the PSP​

Vipps MobilePay posts the card token to the PSP's cardCallbackUrl. The PSP processes the CIT (Customer-Initiated Transaction) and responds within 20 seconds to confirm the agreement. See Card callback.

6. The customer is redirected and the agreement is active​

The customer is redirected to the merchant's merchantRedirectUrl and sees a confirmation. The PSP can now start creating charges according to the agreement terms.

Sequence diagram​

PSP merchant agreement sign-up flow

100%
  1. PSP creates an agreement with Vipps MobilePay (POST /recurring/v3/agreements with cardPassthrough).
  2. Vipps MobilePay returns the vippsConfirmationUrl, agreementId, and chargeId to the PSP.
  3. PSP presents the URL to the user.
  4. User selects a card and confirms the agreement with Vipps MobilePay.
  5. Vipps MobilePay posts a card token to the PSP's cardCallbackUrl.
  6. PSP processes the payment.
  7. PSP returns 200 OK with status RESERVE or CAPTURE to Vipps MobilePay.
  8. Vipps MobilePay notifies the user that the agreement is signed.
  9. User is redirected to the merchantRedirectUrl.
  10. PSP begins charging the user.

More information​

This walkthrough shows a fixed price agreement, but the Recurring API supports several agreement types — fixed price, variable price, flexible price, campaigns, and agreements with an initial charge — and all of them work with card passthrough. For illustrated examples of each, see Payment Agreements in the Recurring API documentation.

For technical details, see the Recurring PSP API guide.

Last updated on