Skip to main content

Subscriptions

The Recurring API and the Login API can be used together making registration and payment of subscriptions simple for your customers.

Login and recurring process

Details​

Step 1. Customer buys a subscription​

A customer wants to buy a subscription through your website or app.

Buy subscription

Step 2. Initiate login​

The customer identifies themselves by logging in with Vipps Login.

From a browser:

  • If they are remembered from earlier, the login will be completed directly there.
  • Otherwise, they will enter their phone number and be taken to the app to the Vipps MobilePay app. See Log in with browser for a detailed example.

From a mobile app:

  • They will be switched over to the app automatically.

Log in

Step 3. Customer confirms login​

The customer will confirm the login in the Vipps MobilePay app.

If the customer was remembered from an earlier login to this site or app, they will skip this step.

Confirm login

The customer will give consent to sharing information with the merchant.

If the customer has previously consented to sharing information with the merchant, they will skip this step.

Give consent to share information

The customer can later see the information they have consented to share, by clicking See your information in the app.

Step 5. Create agreement​

The customer is now logged in to your service and can proceed to set up the payment for the subscription.

The information they have shared with you should be pre-filled in the form, where they have the possibility to update it.

Checkout

Detailed example

Here is an example HTTP POST:

POST:/agreements

With body:

{
   "interval": {
      "unit" : "YEAR",
      "count": 1
   },
   "initialCharge": {
      "amount": 59900,
      "description": "Payment of first year",
      "transactionType": "DIRECT_CAPTURE"
   },
   "pricing": {
      "amount": 59900,
      "currency": "NOK"
   },
   "merchantRedirectUrl": "https://example.com/redirect-url",
   "merchantAgreementUrl": "https://example.com/agreement-url",
   "phoneNumber": "91234567",
   "productName": "1 year subscription",
   "productDescription": "Get 6 editions of our magazine for only 599,- per year.",
}

See Create an agreement for more information.

Step 6. Customer confirms subscription​

The customer accepts the agreement in the Vipps MobilePay app.

Accept agreement

They are returned to the merchant's website or app where the subscription is confirmed.

Confirmation page

Step 7. Capture initial payment (if applicable)​

If you had an initial payment, the charge for this will have been created as part of the agreement. Then, you will need to capture that reserved amount with the capture endpoint.

Detailed example

Here is an example HTTP POST:

POST:/recurring/v3/agreements/{agreementId}/charges/{chargeId}/capture

With body:

{
  "amount": 59900,
  "description": "Yearly subscription renewal."
}

Be sure to check the status of the captured charges.

Step 8. Schedule charges​

Your system must schedule and place all the future agreed charges.

Use the create charge endpoint to place the charge and specify the due date. A charge must be scheduled a minimum of two days before the payment will occur. It will be automatically captured on the due date.

Detailed example

Here is an example HTTP POST:

POST:/recurring/v3/agreements/{agreementId}/charges

With body:

{
  "amount": 59900,
  "transactionType": "DIRECT_CAPTURE",
  "description": "Yearly subscription renewal.",
  "due": "2025-01-01",
  "retryDays": 0
}

Be sure to check the status of the charges.

Step 9. Attach a receipt​

Send a digital receipt for the payment.

Detailed example

Here is an example HTTP POST:

POST:/order-management/v2/recurring/receipts/{orderId}

For paymentType, use recurring for recurring payments. For orderId, use the chargeId of the charge.

Body:

{
  "orderLines": [
    {
        "name": "Web store subscription",
        "id": "12k3lj4l3",
        "totalAmount": 10000,
        "totalAmountExcludingTax": 8000,
        "totalTaxAmount": 2000,
        "taxPercentage": 25,
        "productUrl": "https://www.example.com/yoursubscription",
      },
    },
  ],
  "bottomLine": {
    "currency": "NOK",
  }
}

Relevant pages​

For more information, see:

Sequence diagram​

Sequence diagram for the subscription signup with login flow and initial charge.

Yearly charges: