Self-service integration onboarding (SSIO)

The self-service integration onboarding flow allows merchants to activate integrations of their venues via UI provided by WOLT. This solution designed to activate one venue at time. However, your implementation could support both SSIO and WIO to cover both for self-service and bulk use-cases, if needed.

Checklist

Prerequisites: you are familiar with OAuth flow and your system supports OAuth flows.

1. Build the link in your system where Merchant can initiate the integration of their venues with Wolt.

2. Create a callback page in your system where merchants will be redirected to after onboarding. The redirect will include an authorization code as parameter in the URL.

3. Ensure your system is able to use the authorization code to obtain access and refresh tokens for each venue.

4. Implement token refresh logic for expired tokens.

5. Confirm that you know how to extract the Wolt venue ID from the access token, necessary for certain API calls.

Self-service 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.

[TODO: Add pic]

1. Merchant starts the flow on the partner portal

The merchant (user) initiates the onboarding flow at your portal by clicking a call-to-action, e.g. “Activate on Wolt” button, with the URL source built according to the requirements.

2. Merchant is redirected to Wolt for Developers portal

Your source redirects the user 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.

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

How to?

Build the call-to-action link 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

Request parameters

Handle the redirect 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=offline2

Query parameters

Exchange refresh token for a new access token

Token exchange flowis covered in the Authentication overview section

Ensure the refresh token stays active

Token refresh flow and requirements covered in the Authentication overview section

Redo Self-Service Integration Onboarding

You should allow merchants to redo Self-Service Integration Onboarding directly from your portal. There are two general cases where redo can be helpful:

• Redo onboarding with the same Wolt venue In situations where the initial onboarding encounters issues, this redo option helps to streamline recovery and ensure smooth integration reattempts. In such cases, the Wolt venue remains the same and the main goal is to generate a new authorization code and/or re-trigger the follow-up steps in your system to finalize the onboarding.

• Redo onboarding with a different Wolt venue If the merchant selected the wrong Wolt venue in the original onboarding process, they should be able to redo the onboarding and pick a new Wolt venue. In this case, your system should detect that the new access token has a different Wolt venue ID in the JWT claims. This should trigger any actions needed to unlink the old Wolt venue in your system as well as link the new Wolt venue.

To support the redo process, the following guidelines should be followed:

1. You should always allow merchants to redo the onboarding (either by default or on demand). When they redo the onboarding, you should always get the new tokens and check the Wolt venue ID in the JWT claims.

   1. If the venue ID is different, you should unlink the old Wolt venue and link the new Wolt venue in your system (and potentially other follow-up actions related to the venue change).

   2. If the venue ID is the same, you can still keep the original tokens if they are still valid and operational for the venue (and ignore the tokens received from the redo process).

2. Merchants should receive a clear, informative message indicating the outcome of the redo process. The message should specify whether the tokens and venue ID were kept the same or overwritten.