Skip to main content

Recurring API checklist

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.

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.

Flow to go live​

Choose Merchants if you integrate directly for your own business, or Partners if you integrate on behalf of merchants.

Flow to go live for partner integrations​

When you are done with testing the solution you must:

Download the editable Recurring checklist

Download the PDF— fill it out and send it to developer@vippsmobilepay.com

Fill out platform partner form

Go to production sign up form, fill out the form and submit it

We will then review your checklist and production form. After the checklist and form are approved, we'll send you the information you need to 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.

PurposeEndpoint
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

Branding​

Use the approved buttons​

Show only the approved Vipps MobilePay buttons.

Recommended: The Widget SDK gives you the approved button and takes the customer to the agreement for you: the app on a phone or tablet, or a dialog on a computer. It also keeps the button up to date when the brand changes.

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 the 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 expire. Once a reservation has 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.

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.