Recurring API checklist

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

If you're new to the platform, see Getting started for information about API keys, product activation, and the test environment.

tip

Download the Recurring API checklist as an editable PDF.

Recurring API v3 checklist	Your comments (include your orderId)
Endpoints to integrate
Agreement: Create an agreement POST:/recurring/v3/agreements
Agreement: Retrieve an agreement GET:/recurring/v3/agreements/{agreementId}
Agreement: Update an agreement PATCH:/recurring/v3/agreements/{agreementId}
Agreement: List charges GET:/recurring/v3/agreements/{agreementId}/charges
Charge: Create Charge POST:/recurring/v3/agreements/{agreementId}/charges
Charge: Retrieve a charge GET:/recurring/v3/agreements/{agreementId}/charges/{chargeId}
Charge: Cancel a charge DELETE:/recurring/v3/agreements/{agreementId}/charges/{chargeId}
Charge: Refund a charge POST:/recurring/v3/agreements/{agreementId}/charges/{chargeId}/refund
Charge: Capture a reserved charge POST:/recurring/v3/agreements/{agreementId}/charges/{chargeId}/capture
Quality assurance
Handle errors Monitor the error messages Vipps MobilePay returns from the APIs and correct problems as quickly as possible. It's recommended to log errors emitted by our APIs. This makes it easier to pinpoint what has gone wrong. If you're new to handling errors, see HTTP Responses.
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
Track status with webhooks and polling The merchant must not rely on Redirect alone, but must always poll GET:/recurring/v3/agreements/{agreementId} 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 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 portal.vippsmobilepay.com for normal work.
Use at least two retryDays The success rate of charges increases significantly when retryDays is set to two or more.
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 merchants 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.

Information for partners

Partners, there are additional checklist items for you, as described in Partner checklist.

Partner checklist

Partner checklist	Your comments
Accept partner terms and conditions As a partner, you accept the Partner terms and conditions
Provide technical documentation for merchants How to apply for products (a URL, plain text or PDF is preferred) How to configure and use the solution (a URL, plain text or PDF is preferred) Frequently Asked Questions (FAQs) for merchants (a URL, plain text or PDF is preferred)
Pilot customer Provide one pilot customer to verify the integration in the production environment (send organization number and name).
Description of integration Describe how your integration has been set up, with a link to a demo, or provide screenshots (PDF is preferred).

Send your completed checklist to us at developer@vippsmobilepay.com. Include your Merchant Serial Number, a short description of your solution, and the orderId used in your API requests, so we can verify your integration.

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.

Flow to go live for direct integrations

1. Order Recurring Payments.
2. We complete customer control (KYC, PEP, AML, etc.). The API keys for the production environment are made available on portal.vippsmobilepay.com 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 🎉

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.