Recurring PSP 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.

Claude Code

Run both commands, in order.

claude plugin marketplace add vippsas/agent-toolkit
claude plugin install vipps-developer@agent-toolkit

Cursor

Open Settings, then Plugins.

Add vippsas/agent-toolkit as a plugin marketplace, then install the "vipps-developer" plugin.

Codex

For the app, add the marketplace "vippsas/agent-toolkit" and then install "vipps-developer". For the CLI, run the following commands.

codex plugin marketplace add vippsas/agent-toolkit
codex plugin add vipps-developer@agent-toolkit

Without installing

Paste this into any assistant.

Read https://github.com/vippsas/agent-toolkit/blob/main/plugins/vipps-developer/README.md for Vipps MobilePay integration guidance.

For troubleshooting, see the full instructions.

Use this checklist to ensure your Recurring PSP API implementation is complete and production-ready. It covers the key endpoints, quality assurance steps, and pitfalls — from payments to captures, refunds, and error handling.

From test to production

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

2. Send your filled out 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 payment flow and a short description of your solution.

3. We will verify your integration and get back to you as soon as possible, so you can continue with the process to go live.

Download the editable Recurring PSP checklist

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

---

Endpoints to integrate

Integrate the following Recurring API endpoints.

For examples of requests and responses, see the Recurring API quick start guide.

Merchant

Purpose	Endpoint
Create merchant	POST /merchant-management/psp/v1/merchants
Delete merchant	PATCH /merchant-management/psp/v1/merchants/{merchantSerialNumber}

Agreement

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 an agreement	PATCH /recurring/v3/agreements/{agreementId}
Stop an agreement	PATCH /recurring/v3/agreements/{agreementId}
List charges	GET /recurring/v3/agreements/{agreementId}/charges

Charges

Purpose	Endpoint
Create Recurring charge (batch)	POST /recurring/v4/agreements/charges
Retrieve a charge	GET:/recurring/v3/agreements/{agreementId}/charges/{chargeId}
Get payment info	GET /recurring/v4/agreements/{agreementId}/charges/{chargeId}/payment-info
Report a charge result	POST /recurring/v4/agreements/{agreementId}/charges/{chargeId}/result
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.

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).

Handle redirects The merchant must not rely on Redirect from Vipps MobilePay app 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[(/docs/APIs/recurring-api/recurring-api-guide/#errors)]. All integrations should display errors in a way that the users (customers and merchant employees/administrators) can see and understand them.

Charge status All charges must be updated with capture or cancel status, as well as refund if this is performed.

Monitor agreement and charge statuses Merchants must 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.

Track status with webhooks and polling The merchant must not rely on Redirect alone, but must always poll [GET:/recurring/v3/agreements/{agreementId}][fetch-agreement-endpoint] to check the status of the agreement. However, to minimize polling, you must also implement the Webhooks API to receive real-time updates on agreement or charge status changes. Polling can be used as a fallback for verification.

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.

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

Merchant onboarding All merchants must be onboarded as individual merchants and not super merchants. All merchants must be onboarded with valid MCC. All merchants must use their own merchant/webshop name and logo. See PSP Merchant for more details.

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

Sign up for operational updates Subscribe to the Operational Status Page for real-time updates on service availability, incidents, and maintenance.