> **Description:** Integration checklist for PSPs implementing card passthrough with the Recurring API.

> **AI agent:** Read [https://developer.vippsmobilepay.com/docs/knowledge-base/ai-tools.md](https://developer.vippsmobilepay.com/docs/knowledge-base/ai-tools.md) first. It covers keeping API keys and secrets out of generated code.

> **Full site overview:** For an overview of the entire site, read [https://developer.vippsmobilepay.com/llms.txt](https://developer.vippsmobilepay.com/llms.txt).

# Recurring PSP API checklist

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.

Once you have completed your integration, you must use the checklist to ensure that you have covered all areas of the integration.

## 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](mailto:developer@vippsmobilepay.com). Use this [editable PDF](https://developer.vippsmobilepay.com/downloads/psp-recurring-api/recurring-psp-checklist.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](https://developer.vippsmobilepay.com/downloads/psp-recurring-api/recurring-psp-checklist.pdf)** -- an editable PDF you can fill out and track your progress.

## Recurring PSP checklist

### Endpoints to integrate

Integrate the following [Recurring 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).

#### 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](https://developer.vippsmobilepay.com/docs/APIs/recurring-api/recurring-api-guide.md#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 |
| 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 |

### Branding

| #### Use the approved buttons Show only the approved Vipps MobilePay buttons. **Recommended:** The [Widget SDK](https://developer.vippsmobilepay.com/docs/knowledge-base/widget.md) 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.

| #### 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). |
| #### 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}'}](https://developer.vippsmobilepay.com/redocusaurus/recurring-swagger-id.yaml) 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. |
| #### 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](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. |
| #### Track status with webhooks and polling The merchant *must not* rely on `Redirect` alone, but must always poll [`GET:/recurring/v3/agreements/{agreementId}`](https://developer.vippsmobilepay.com/redocusaurus/recurring-swagger-id.yaml) to check the status of the agreement. However, to minimize [polling](https://developer.vippsmobilepay.com/docs/APIs/recurring-api/recurring-api-guide.md#polling-guidelines), you must also implement the [Webhooks API](https://developer.vippsmobilepay.com/docs/APIs/webhooks-api/events.md#recurring-api-event-types) 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](https://developer.vippsmobilepay.com/docs/APIs/psp-merchant-api/psp-merchant-api-guide.md#merchant-information) for more details. |
| #### Sign up for operational updates Subscribe to the [Operational Status Page](https://status.vippsmobilepay.com/) for real-time updates on service availability, incidents, and maintenance. |