Subscriptions
The Recurring API and the Login API can be used together making registration and payment of subscriptions simple for your customers.
Details
Step 1. Customer buys a subscription
A customer wants to buy a subscription through your website or app.
Step 2. Initiate login
The customer identifies themselves by logging in with Vipps MobilePay 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 or MobilePay app. See the Login quick start guide for a detailed example.
From a mobile app:
- They will be switched over to the app automatically.
Step 3. Customer confirms login
The customer will confirm the login in the Vipps or MobilePay app.
If the customer was remembered from an earlier login to this site or app, they will skip this step.
Step 4. Customer gives consent to share information
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.
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 prefilled in the form, where they have the possibility to update it.
Detailed example
Here is an example HTTP POST:
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": "4712345678",
"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 or MobilePay app.
They are returned to the merchant's website or app where the subscription is confirmed.
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": 2
}
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,
"taxRate": 2550,
"productUrl": "https://www.example.com/yoursubscription",
},
},
],
"bottomLine": {
"currency": "NOK",
}
}
Sequence diagram
Sequence diagram for the subscription signup with login flow and initial charge.
Yearly charges:
Next steps
Review some related pages: