Recurring API checklist

Did you try out the Recurring API? Use this checklist as your integration requirement specification to ensure your Recurring API implementation is complete and production-ready.

It covers the key endpoints, quality assurance steps and pitfalls — from agreements to charges, and error handling. Once you have completed your integration, you must use the checklist to ensure that you have covered all areas of the integration.

Partners

Flow to go live for partner integrations

1. Complete your testing of the Recurring API. Use the list below to ensure you cover all areas of the integration before you submit the checklist.

2. Send your filled out Recurring checklist to us at developer@vippsmobilepay.com.
   Use this editable PDF to fill out and submit. Request examples in the checklist must be no more than 1 month old at the time you submit the checklist.
   Together with the checklist, please include a video of your agreement flow and a short description of your solution.

3. Fill out production sign up form with details about your company and solution.

4. We will verify your integration and get back to you as soon as possible. After the checklist is approved, we'll send you the information you need to go live.

Download the editable Recurring checklist

📋 Download the PDF - an editable PDF you can fill out and track your progress.

Merchants

Flow to go live for direct integrations

1. Order Recurring Payments.
2. We complete customer control (KYC, PEP, AML, and other compliance checks). The API keys for the production environment are made available on the business portal as soon as the customer control is completed, independently of this checklist.
3. We notify you when you can retrieve your API keys.
4. Complete all the checklist items.
5. Verify the integration in the test environment by checking that there are test agreements and charges with your specified orderId in the test environment, with the following states:
   • A complete Agreement ending in ACTIVE.
   • A complete Agreement ending in STOPPED.
   • A complete "type":"RECURRING" Charge ending in CHARGED.
   • A complete "type":"RECURRING" Charge ending in REFUNDED.
6. Start using the MSN and API keys in the production environment.
7. Verify the integration in the production environment (similar to step 5).
8. Verify that agreements contain complete and accurate information, including price, interval, product description and product name.
9. Partners only: Send your checklist to developer@vippsmobilepay.com. We don't do any kind of activation or make any changes based on this checklist, we just use it to verify that you have done the integration.
10. Go live 🎉

Recurring checklist

Endpoints to integrate

It is important that you integrate all non-optional API endpoints. For examples of requests and responses, see the Recurring API quick start guide.

Purpose	Endpoint
Create an agreement	POST:/recurring/v3/agreements
Create an agreement with initial charge	POST:/recurring/v3/agreements
Create an agreement with price campaign Optional feature	POST:/recurring/v3/agreements
Create an agreement with period campaign Optional feature	POST:/recurring/v3/agreements
Create an agreement with event campaign Optional feature	POST:/recurring/v3/agreements
Retrieve an agreement	GET:/recurring/v3/agreements/{agreementId}
Update agreement details	PATCH:/recurring/v3/agreements/{agreementId}
Stop an agreement	PATCH:/recurring/v3/agreements/{agreementId}
List charges	GET:/recurring/v3/agreements/{agreementId}/charges
Create charge	POST:/recurring/v3/agreements/{agreementId}/charges
Retrieve a charge	GET:/recurring/v3/agreements/{agreementId}/charges/{chargeId}
Cancel a charge	DELETE:/recurring/v3/agreements/{agreementId}/charges/{chargeId}
Refund a charge	POST:/recurring/v3/agreements/{agreementId}/charges/{chargeId}/refund
Capture a reserved charge	POST:/recurring/v3/agreements/{agreementId}/charges/{chargeId}/capture

Quality assurance

Ensure that your implementation complies with our requirements and recommendations.

Monitor agreement and charge statuses Merchants should listen to Webhooks to track critical events such as: Agreement cancellations Activation of agreements Charge-related updates (e.g., successful or failed charges) This ensures merchants do not request payments on canceled agreements and avoid errors caused by outdated agreement statuses. Webhooks provide real-time updates. Use polling as a fallback mechanism to verify agreement and payment statuses if webhook delivery fails.

Handle redirects The merchant must not rely on Redirect from Vipps MobilePay alone, but must rely on either webhook or poll GET:/recurring/v3/agreements/{agreementId} to check the status of the agreement. The merchant must handle that the returnUrl URL is opened in the default browser on the phone, and not in a specific browser, in a specific tab, in an embedded browser, requiring a session token, etc. Follow our recommendations regarding handling redirects.

Handle errors Make sure to handle all errors. All integrations should display errors in a way that the users (customers and merchant employees/administrators) can see and understand them.

Proper logging All integrations should log error responses to be used for later reference in troubleshooting. Logs must include endpoint, headers, request body, error code and message.

Include standard HTTP headers Send the HTTP headers in all API requests for better tracking and troubleshooting (mandatory for partners and platforms, who must send these headers as part of the checklist approval).

Avoid integration pitfalls

These are the most common pitfalls to avoid to ensure best user experience.

Transaction type Ensure that the correct transaction type is used for charges based on use case. Either DIRECT_CAPTURE or RESERVE_CAPTURE

Complete capture before expiration date For reserve capture payments, ensure to complete captures before the reservations expires. Once a reservation is expired it is no longer possible to capture.

Use at least two retryDays The success rate of charges increases significantly when retryDays is set to two or more.

Due date minimum 1 day in advance Recurring charges must be requested minimum 1 day in advance, and maximum 2 years in advance.

Provide subscription tools The merchant must have a way for the user to manage and stop their subscription in merchantAgreementUrl in their agreement. This should result in a timely update of the Vipps MobilePay agreement.

Follow design guidelines The Vipps MobilePay branding must be according to the design guidelines.

Educate customer support Make sure your customer support has all the tools and information they need available in your system, through the APIs listed in the first item in this checklist, and that they do not need to visit the business portal for normal work.

Handle cross-border payments Vipps MobilePay is available to users across the Nordic countries and offers cross-border payments. Merchants must be able to handle customers from outside their country.

tip

Operational Status Page

We recommend that you subscribe to the Vipps MobilePay Operational Status Page for real-time updates on service availability, incidents, and maintenance.