Wolt-led integration onboarding

Overview

The Wolt-led integration onboarding flow enables Wolt's technical account managers to onboard integrations for venues with integration partners.

This process reduces manual tasks and minimizes the risk of human error by automating the credential exchange between Wolt and your system. During the integration onboarding, Wolt’s system will exchange credentials with your system. These credentials grant you access to Wolt’s APIs for the integrated venue, allowing you to manage the venue on Wolt’s platform.

Integration onboarding flow

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

1. Wolt initiates integration onboarding for a venue

Wolt's technical account manager triggers integration onboarding for one or more venues. For Wolt's technical account manager to start integration on a venue it needs to be mapped from your system to Wolt's. This is done by providing a list of venues to Wolt. The list should include the venue ID from your system and the corresponding venue from Wolt's system.

2. Wolt's system sends authorization code to integration partner

When integration onboarding is completed, Wolt’s system sends an authorization code for each integrated venue to your endpoint. For example if five venues are integrated, your system will receive five separate requests.

3. 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 Wolt-led 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 self-service 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 self-service integration onboarding, only the authorization code endpoint URL is required. Otherwise, you need to provide the following details to Wolt:

• Name: The name of your service.
• Redirect URLs: A URL to use for generating a authorization code. Note that this is only used for authorization code generation, no redirects are actually done. If you support self-service integration onboarding Wolt will use one of the redirect URLs you have provided.
• 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.
• Authorization code endpoint URL: The endpoint URL where Wolt sends the authorization code after the integration onboarding is complete.
• Authorization code endpoint API key: A API key to include in the webhook notification send to the authorization code endpoint. This key is used to verify that the request is coming from Wolt. Must be at least 32 characters in length. If needed Wolt can generate this for you.

Authentication

Venues integrated through the Wolt-led 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.

Endpoint to receive authorization code from Wolt

Your system must expose an HTTPS endpoint that accepts a POST request containing the authorization code and the redirect URL. For each venue that completes integration via the Wolt-led onboarding flow, Wolt will send a distinct webhook notification to this endpoint.

The request header X-API-Key will include the authorization code endpoint API key. You must verify that it matches the one you have provided (or that has been provided to you).

The authorization code is single-use and valid for 1 hour. If it expires before use, you must request the venue to be re-integrated.

When your system receives the POST request, it should:

1. Verify the API key in the request header (X-API-Key).
2. Extract the authorization code and redirect URL from the request payload.
3. Exchange the authorization code for access and refresh tokens.
4. Obtain the Wolt venue ID from the access token.
5. Return a 2xx status code (e.g., 200 OK) if the request is processed successfully. Any other status code will be treated by Wolt as a failure.

Example request

{
  "authorization_code": "ory_ac_mhQXeiZ3YZ1A4rMUOumukxAkTCiLEQP65tCTWgx7G8M.R7RfKSPPhgHN6Q5DqwvqwxyVVualZZLpRyurCgY0WMU",
  "redirect_url": "https://partner-redirect-url.com",
  "partner_venue_id": "664eeda2228d49c9ff6b1f89"
}

Request fields

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. Request test integration: Ask Wolt technical account manager to initiate Wolt-led integration onboarding with your test venues.
2. Verify your authorization code endpoint: Ensure that the authorization code endpoint on your system correctly receives the authorization code and any other necessary data.
3. Exchange the authorization code for access and refresh tokens: Verify the authorization code works by exchanging it for access and refresh tokens.
4. 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.
5. 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.
6. 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.
7. Re-verify the Access Token: Repeat step 5 to confirm that the token continues to function properly.
8. Reset the test integration: Call the designated endpoint to reset the test integration, making the venue available for the next test run.