> **Description:** Comprehensive integration checklist covering setup requirements, webhook handling, testing scenarios, and production readiness verification.

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

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

1. Send your filled out Recurring checklist to us at [developer@vippsmobilepay.com](mailto:developer@vippsmobilepay.com).
Use this [editable PDF](https://developer.vippsmobilepay.com/downloads/recurring-api/recurring-checklistv2.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.

1. Fill out [production sign up form](https://vippsmobilepay.com/en-NO/partner-form) with details about your company and solution.

1. 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 PDF](https://developer.vippsmobilepay.com/downloads/recurring-api/recurring-checklistv2.pdf)** -- an editable PDF you can fill out and track your progress.

## Flow to go live for direct integrations

1. Order [*Recurring Payments*](https://vippsmobilepay.com/en-NO/online/billing-recurring).
1. 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](https://portal.vippsmobilepay.com)
   as soon as the customer control is completed, independently of this checklist.
1. We notify you when you can
   [retrieve your API keys](https://developer.vippsmobilepay.com/docs/knowledge-base/portal.md#how-to-find-the-api-keys).
1. Complete all the checklist items.
1. Verify the integration in the test environment by checking that
   there are test agreements and charges with your specified `orderId` in the
   [test environment](https://developer.vippsmobilepay.com/docs/knowledge-base/test-environment.md),
   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`.
1. Start using the MSN and API keys in the production environment.
1. Verify the integration in the production environment (similar to step 5).
1. Verify that agreements contain complete and accurate information, including `price`, `interval`, `product description` and `product name`.
1. Partners only: Send your checklist to [developer@vippsmobilepay.com](mailto: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.
1. Go live

## Recurring checklist

## Endpoints to integrate

It is important that you integrate *all* non-optional [API endpoints](https://developer.vippsmobilepay.com/redocusaurus/recurring-swagger-id.yaml).
For examples of requests and responses, see the [Recurring API quick start guide](https://developer.vippsmobilepay.com/docs/APIs/recurring-api/recurring-api-quick-start.md).

| Purpose | Endpoint |
| --- | --- |
| Create an agreement | [`POST:/recurring/v3/agreements`][draft-agreement-endpoint] |
| Create an agreement with [initial charge](https://developer.vippsmobilepay.com/docs/APIs/recurring-api/recurring-api-guide.md#initial-charge) | [`POST:/recurring/v3/agreements`][draft-agreement-endpoint] |
| Create an agreement with price campaign *Optional feature* | [`POST:/recurring/v3/agreements`][draft-agreement-endpoint] |
| Create an agreement with period campaign *Optional feature* | [`POST:/recurring/v3/agreements`][draft-agreement-endpoint] |
| Create an agreement with event campaign *Optional feature* | [`POST:/recurring/v3/agreements`][draft-agreement-endpoint] |
| Retrieve an agreement | [`GET:/recurring/v3/agreements/{agreementId}`][fetch-agreement-endpoint] |
| Update agreement details | [`PATCH:/recurring/v3/agreements/{agreementId}`][update-agreement-patch-endpoint] |
| Stop an agreement | [`PATCH:/recurring/v3/agreements/{agreementId}`][update-agreement-patch-endpoint] |
| List charges | [`GET:/recurring/v3/agreements/{agreementId}/charges`][list-charges-endpoint] |
| Create charge | [`POST:/recurring/v3/agreements/{agreementId}/charges`][create-charge-endpoint] |
| Retrieve a charge | [`GET:/recurring/v3/agreements/{agreementId}/charges/{chargeId}`][fetch-charge-endpoint] |
| Cancel a charge | [`DELETE:/recurring/v3/agreements/{agreementId}/charges/{chargeId}`][cancel-charge-endpoint] |
| Refund a charge | [`POST:/recurring/v3/agreements/{agreementId}/charges/{chargeId}/refund`][refund-charge-endpoint] |
| Capture a reserved charge | [`POST:/recurring/v3/agreements/{agreementId}/charges/{chargeId}/capture`][capture-charge-endpoint] |

### Quality assurance

Ensure that your implementation complies with our requirements and recommendations.

| ### Monitor agreement and charge statuses Merchants should listen to [Webhooks](https://developer.vippsmobilepay.com/docs/APIs/webhooks-api/events.md#recurring-api-event-types) 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}`][fetch-agreement-endpoint] 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](https://developer.vippsmobilepay.com/docs/knowledge-base/redirects.md). |
| ### Handle errors Make sure to handle [all errors](https://developer.vippsmobilepay.com/docs/APIs/recurring-api/recurring-api-guide.md#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](https://developer.vippsmobilepay.com/docs/knowledge-base/http-headers.md) 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](https://developer.vippsmobilepay.com/docs/APIs/recurring-api/recurring-api-guide.md#transaction-type) is used for charges based on use case. Either DIRECT_CAPTURE or RESERVE_CAPTURE |
| --- |
| ### Complete capture before expiration date For [reserve capture](https://developer.vippsmobilepay.com/docs/knowledge-base/reserve-and-capture.md#reserve-capture) payments, ensure to complete captures before the reservations expire. 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`](https://developer.vippsmobilepay.com/docs/APIs/recurring-api/recurring-api-guide.md#charge-retries) is set to two or more. |
| ### Due date minimum 1 day in advance Recurring charges must be requested [minimum 1 day](https://developer.vippsmobilepay.com/docs/APIs/recurring-api/recurring-api-guide.md#due-date) 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](https://developer.vippsmobilepay.com/docs/knowledge-base/design-guidelines.md). |
| ### 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](https://portal.vippsmobilepay.com) for normal work. |
| ### Handle cross-border payments Vipps MobilePay is available to users across the [Nordic countries and offers cross-border payments](https://developer.vippsmobilepay.com/docs/knowledge-base/across-borders.md). 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](https://status.vippsmobilepay.com/) for real-time updates on service availability, incidents, and maintenance.

[draft-agreement-endpoint]: https://developer.vippsmobilepay.com/redocusaurus/recurring-swagger-id.yaml
[fetch-agreement-endpoint]: https://developer.vippsmobilepay.com/redocusaurus/recurring-swagger-id.yaml
[update-agreement-patch-endpoint]: https://developer.vippsmobilepay.com/redocusaurus/recurring-swagger-id.yaml
[force-accept-agreement-endpoint]: https://developer.vippsmobilepay.com/redocusaurus/recurring-swagger-id.yaml
[list-charges-endpoint]: https://developer.vippsmobilepay.com/redocusaurus/recurring-swagger-id.yaml
[create-charge-endpoint]: https://developer.vippsmobilepay.com/redocusaurus/recurring-swagger-id.yaml
[fetch-charge-endpoint]: https://developer.vippsmobilepay.com/redocusaurus/recurring-swagger-id.yaml
[cancel-charge-endpoint]: https://developer.vippsmobilepay.com/redocusaurus/recurring-swagger-id.yaml
[capture-charge-endpoint]: https://developer.vippsmobilepay.com/redocusaurus/recurring-swagger-id.yaml
[refund-charge-endpoint]: https://developer.vippsmobilepay.com/redocusaurus/recurring-swagger-id.yaml
[userinfo-endpoint]: https://developer.vippsmobilepay.com/redocusaurus/userinfo-swagger-id.yaml
[access-token-endpoint]: https://developer.vippsmobilepay.com/redocusaurus/access-token-swagger-id.yaml
[vipps-test-environment]: https://developer.vippsmobilepay.com/docs/knowledge-base/test-environment.md

> **Full site overview:** For every page in this documentation, read [https://developer.vippsmobilepay.com/llms.txt](https://developer.vippsmobilepay.com/llms.txt).