Self-service integration onboarding

Overview

The self-service integration onboarding flow allows merchants to activate integrations for their venues without requiring manual activation from the integration partner.

As an integration partner (e.g. POS or middleware), self-service integration onboarding enables you to offer merchants a seamless integration experience. Once a merchant completes the integration process, your system exchanges credentials with Wolt. These credentials grant you access to Wolt’s APIs for the integrated venue on behalf of the merchant, allowing you to manage the venue on Wolt’s platform.

Self-service integration onboarding streamlines the onboarding process by reducing communication overhead, while giving merchants the freedom to manage their integration independently.

Integration onboarding flow

Self-service integration onboarding consists of multiple steps that happen between the merchant, your system, and Wolt. The following diagram illustrates the flow of the integration onboarding process.

1. Merchant starts the flow on the partner portal

The merchant starts the onboarding flow in your portal by clicking a call to action, e.g. “Get onto Wolt” button, on their venue’s page.

2. Merchant is redirected to Wolt for Developers portal

After clicking the call to action to integrate with Wolt, your portal redirects the merchant to the Wolt for Developers portal. There the merchant signs in using their Wolt account. This allows Wolt to identify the merchant and display their venues available for integration.

3. Merchant selects a venue and authorizes the integration partner

After viewing the list of their venues available for integration, the merchant selects the venue that matches the one they initiated the integration for. They then grant permission for your system to access and manage the venue using Wolt’s APIs.

4. Merchant is taken back to the partner portal with authorization code

Once the merchant grants authorization, Wolt generates an authorization code and redirects the merchant back to your portal with the code included in the URL.

5. Partner system exchanges the authorization code for tokens

Your system extracts the authorization code from the redirect URL and sends it to Wolt’s authentication service to obtain both an access token and a refresh token. The access token enables communication with Wolt’s APIs, while the refresh token is used to request a new access token once the current one expires. Typically, the authorization code is used only during the initial exchange, after which you should rely solely on the refresh token.

Partner onboarding checklist

To implement the self-service integration onboarding flow, you need to implement specific components listed below.

What Wolt provides to you

• OAuth2 client credentials: Includes client_id and client_secret for authentication. If you already support Wolt-led integration onboarding, you may use existing credentials.
• Wolt accounts and test venue access: Access to Wolt accounts and test venues for building and testing the integration onboarding flow.
• Postman collection: A Postman collection that provides an overview of available endpoints to assist with development and testing.

Required information from integration partners

If you already support Wolt-led integration onboarding, no additional information is needed. Otherwise, you need to provide the following details to Wolt:

• Name: The name of your service.
• Redirect URLs: The URLs you can use for redirecting merchants back to your portal after they complete integration on Wolt. If you want to be able to redirect merchants to multiple different URLs, each must be explicitly specified. Wildcards are not supported.
• Order webhook URL: The URL where Wolt sends order status updates.
• Order webhook client secret: A secret key for verifying that order updates are sent from Wolt.
• Order events which trigger notifications: A list of events for which you want to receive notifications for. Supported events include CREATED, PRODUCTION, READY, DELIVERED, and CANCELLED.
• Emails and phone numbers: Contact information for test accounts provided by Wolt, which you can use to test the integration.

Authentication

Venues integrated through the self-service integration onboarding authenticate with Wolt APIs using OAuth 2.0. As an integration partner, your system will use the authorization code flow to obtain access and refresh tokens. These tokens provide secure access for managing venues on behalf of merchants.

For more details on how authentication works, see integration onboarding authentication.

Add a call to action on your portal

For a merchant to start the integration onboarding process with Wolt, you need to include a call to action (e.g., a button or link) on your portal for each venue that hasn’t been integrated with Wolt. When the merchant triggers this call to action, they should be redirected to the Wolt for Developers portal via a URL that you construct according to specific guidelines.

For example, using the values from the table below, the URL to start the integration onboarding could look like this:

https://developer.development.dev.woltapi.com/integrate?client_id=38dc735a-09a9-4cb3-903c-6e4ffd9f6076&venue_name=Bob's+Burger&venue_address=Locomotive+Road+12&redirect_url=https://www.partner-site.com/callback&state=e5f9cdc78f39d99e

To construct the redirect URL correctly, follow the specifications outlined below.

Base URL

Query parameters

Handle merchant coming back to your portal after completing integration on Wolt

When starting the integration onboarding, you construct a URL that includes the redirect URL and state parameters. After the merchant completes the integration on Wolt, they will be redirected to the redirect URL with the authorization code and state appended as a query parameters.

The authorization code is used to get access and refresh tokens. It is single-use and valid for 1 hour. If the code is not used before it expires, the integration has to be done again. You must contact Wolt first to reset the already integrated venue before it becomes available for re-integration.

Upon receiving the redirect back to your portal, your system must:

1. Verify that the opaque value provided in the state parameter of the initial URL matches the value returned in the redirect URL. This helps step helps protect against cross-site request forgery (CSRF).
2. Extract the authorization code from the code parameter and exchange it for access and refresh tokens.
3. Obtain the Wolt venue ID from the access token

Here’s an example of the URL the merchant will be redirected to after completing the integration onboarding:

https://www.partner-site.com/callback?code=ory_ac_3Xht4Qcqo4MF6tKrxRu7Fd4zYYIZ6CmploWAysX9Tpo&state=e5f9cdc78f39d99e&scope=offline

Query parameters

Logic to exchange refresh token for a new access token

Once you have a refresh token, it can be used to get a new access token and refresh token when the current access token expires.

When you exchange the refresh token for a new access token, Wolt will return both a new access token and a new refresh token. The new refresh token will replace the old one, and the previous refresh token will no longer be valid.

Your system must store the new refresh token and use it for the next request to get a new access token.

Logic to ensure the refresh token stays active

The refresh token will expire if it is unused for 30 days, requiring re-integration. To avoid disruption and ensure continued access to Wolt APIs, your system must proactively maintain the refresh token's validity.

To keep the refresh token alive during periods of inactivity, your system should automatically exchange it for a new access and refresh tokens before the refresh token expires. This ensures that the refresh token remains active and prevents expiration.

Testing the implementation

During the build stage, Wolt provides several venues for testing your integration. In the development environment, you can perform integration onboarding on test venues as many times as needed.

1. Integrate a venue via the Self-Service Integration Onboarding Flow: Follow the onboarding process to integrate a test venue.
2. Exchange the authorization code for access and refresh tokens: Once you complete the integration on Wolt, ensure that your system automatically exchanges the authorization code for access and refresh tokens.
3. Obtain the Wolt venue ID from the access token: The venue ID may be required for subsequent requests. See the detailed process in our dedicated guide.
4. Verify the access token: Confirm that the access token works by performing the following actions for the venue and its menu.
   • Create a menu
   • Set the venue's opening hours
   • Update the venue’s online status
   • Test the order flow:
     • Submit an order from the Wolt test website (accessible via Merchant Admin → Venue → Menu editor → View on Wolt.com, or contact your account manager).
     • Use Adyen test cards (consumer card type) for payment methods.
     • Use the endpoints provided in the Order API to ensure the token works for your specific use case.
5. Obtain a new access token with the refresh token: Use the refresh token to obtain a new access token.
   • Ensure your system does not perform parallel requests to refresh the token.
   • Simulate scenarios where your system fails to persist the refresh token, verify fallback mechanisms to prevent token loss.
   • Confirm that your system refreshes the tokens within a 30-day window to avoid expiration due to inactivity.
6. Re-verify the Access Token: Repeat step 4 to confirm that the token continues to function properly.
7. Reset the test integration: Call the designated endpoint to reset the test integration, making the venue available for the next test run.