> **Description:** Visual walkthrough of the agreement sign-up flow for PSPs using card passthrough with the Recurring 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 an overview of the entire site, read [https://developer.vippsmobilepay.com/llms.txt](https://developer.vippsmobilepay.com/llms.txt).

# How agreement sign-up works for PSPs

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

## Details

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`](https://developer.vippsmobilepay.com/redocusaurus/recurring-swagger-id.yaml), 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](https://developer.vippsmobilepay.com/docs/APIs/psp-recurring-api/recurring-psp-api-guide.md#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](https://developer.vippsmobilepay.com/docs/knowledge-base/landing-page.md) 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](https://developer.vippsmobilepay.com/docs/APIs/psp-recurring-api/recurring-psp-api-guide.md#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

```mermaid
sequenceDiagram
    autonumber
    participant PSP
    participant VM as Vipps MobilePay
    actor User

    PSP->>VM: POST /recurring/v3/agreements (with cardPassthrough)
    VM-->>PSP: vippsConfirmationUrl, agreementId, chargeId
    PSP->>User: Present URL to user
    User->>VM: User selects card and confirms agreement
    activate VM
    VM->>PSP: POST cardCallbackUrl (card token)
    PSP->>PSP: Process payment
    PSP-->>VM: 200 OK (status: RESERVE/CAPTURE)
    VM-->>User: Agreement signed
    deactivate VM
    User-->PSP: Redirect to merchantRedirectUrl
    PSP->>User: Starts charging user
```

  PSP creates an agreement with Vipps MobilePay (POST /recurring/v3/agreements with cardPassthrough).
  Vipps MobilePay returns the vippsConfirmationUrl, agreementId, and chargeId to the PSP.
  PSP presents the URL to the user.
  User selects a card and confirms the agreement with Vipps MobilePay.
  Vipps MobilePay posts a card token to the PSP's cardCallbackUrl.
  PSP processes the payment.
  PSP returns 200 OK with status RESERVE or CAPTURE to Vipps MobilePay.
  Vipps MobilePay notifies the user that the agreement is signed.
  User is redirected to the merchantRedirectUrl.
  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](https://developer.vippsmobilepay.com/docs/APIs/recurring-api/how-it-works/payment-agreement/README.md) in the Recurring API
documentation.

For technical details, see the [Recurring PSP API guide](https://developer.vippsmobilepay.com/docs/APIs/psp-recurring-api/recurring-psp-api-guide.md#agreement-sign-up).