Self-Onboarding

API Reference — Stores API Reference — Webhooks

Self-onboarding allows POS integrators to associate new stores to their integration autonomously, without requiring manual intervention per store. Once your integration is set up, your system can provision and deprovision stores programmatically at any scale.

Prerequisites

Self-onboarding uses two kinds of credentials, and you get them in different ways. Do not mix them up:

CredentialsUsed forHow you get them
Integrator M2M (client_id and client_secret)Integrator token (X-Authorization header)One-time setup by a Technical Account Manager (TAM), who creates the Integration entity and the clientId in Auth0.
Merchant-flow client_id and its callback URIsMerchant token (Authorization-Partners header)Self-service from the Self Onboarding module of the Integrations Portal, without contacting your TAM. See Merchant token.

After the initial setup, all provisioning operations are fully self-service.

Base URL

All endpoints in this guide use the base path /api/v2/restaurants-integrations-public-api.

For country domains, see Country Domains. For development, use https://api.dev.rappi.com.

Example — GET /stores/integration-status in Colombia production:

GET https://api.rappi.com.co/api/v2/restaurants-integrations-public-api/stores/integration-status

Authentication

Self-onboarding uses a two-token model. Your application needs to obtain two independent tokens before calling any self-onboarding endpoint:

Integrator token (your credentials)

Obtain a machine-to-machine (M2M) token using your client_id and client_secret. For details on how to obtain this token, see the Authentication guide.

This token is long-lived (configurable TTL). Cache it and only refresh when it expires.

Merchant token (your merchant's credentials)

To access a merchant's stores, your application must redirect the merchant through Rappi's OAuth2 Authorization Code + PKCE flow on Portal Partners. This authorizes your integration to act on the merchant's behalf.

EnvironmentAuthorization URLToken URL
Productionhttps://login.partners.rappi.com/authorizehttps://login.partners.rappi.com/oauth/token
Developmenthttps://login.partners.dev.rappi.com/authorizehttps://login.partners.dev.rappi.com/oauth/token

ℹ️ The examples below use the Production environment. Replace the URLs with the Development endpoints shown above when testing.

Register your client_id and callback URIs

You manage the client_id of this flow and your redirect_uri yourself from the Self Onboarding module of the Integrations Portal (Production · Development). You do not need to contact your TAM.

  1. Open the Self Onboarding module and select your integration.
  2. Click Activate Self Onboarding in the environment you are going to use. Rappi creates your integration's Auth0 application.
  3. Copy the Client ID. The module also shows the Authorization URL and Token URL from the table above.
  4. Under Callback URIs, type your redirect_uri in New callback URI and click Add. You can register several and remove the ones you no longer use with Delete.

Register the callback URIs in the same environment (Development or Production) as the authorization URL you are going to use.

Callback URI rules

  • It must be an absolute URL that uses https, in every environment (Development and Production). http://localhost is not accepted.
  • It must include a host and must not contain credentials (user:password@).
  • Maximum length: 2048 bytes (UTF-8).
  • No #fragment.
  • No wildcards (*): matching is exact.
  • It must match character by character the redirect_uri you send to /authorize and /oauth/token (including letter case, port, query string and trailing slash).

Callback URL mismatch error

If, when you redirect the merchant to /authorize, the login fails with Callback URL mismatch, the redirect_uri in your request does not match any registered callback URI. To fix it:

  1. Compare the redirect_uri in your request with the Callback URIs list in the module.
  2. If it is not there, add it. If it differs by even one character, register the exact version or adjust your request.
  3. Use the same value in /authorize and in /oauth/token.

Step 1 — Generate a PKCE code challenge

Before redirecting, your backend must generate a PKCE pair:

  1. Generate a cryptographically random code_verifier (43–128 URL-safe characters)
  2. Compute code_challenge = BASE64URL(SHA256(code_verifier))

Step 2 — Redirect the merchant

Build the authorization URL and redirect the merchant's browser:

GET https://login.partners.rappi.com/authorize ?client_id=YOUR_CLIENT_ID &redirect_uri=YOUR_REDIRECT_URI &response_type=code &scope=openid profile email &code_challenge=YOUR_CODE_CHALLENGE &code_challenge_method=S256 &state=YOUR_RANDOM_STATE

⚠️ Always validate that the state value in the redirect matches what you sent — this prevents CSRF attacks.

Step 3 — Merchant authenticates

The merchant logs in with their Rappi Portal Partners credentials. Once done, Portal Partners redirects back to your redirect_uri with an authorization code:

GET YOUR_REDIRECT_URI?code=AUTHORIZATION_CODE&state=YOUR_RANDOM_STATE

Step 4 — Exchange the code for a merchant JWT

Your backend exchanges the authorization code for a merchant JWT:

POST https://login.partners.rappi.com/oauth/token Content-Type: application/x-www-form-urlencoded grant_type=authorization_code &code=AUTHORIZATION_CODE &client_id=YOUR_CLIENT_ID &code_verifier=YOUR_CODE_VERIFIER &redirect_uri=YOUR_REDIRECT_URI

ℹ️ No client_secret is required — this is a public OAuth2 client using PKCE.

The response is a JSON object with several tokens. Use the id_token field — that is the merchant JWT, and it is the one carrying the email in its claims:

{ "access_token": "<header>.<encrypted_key>.<iv>.<ciphertext>.<tag>", "id_token": "<header>.<payload>.<signature>", "token_type": "Bearer" }

The flow does not request offline_access, so the response carries no refresh_token: when the id_token expires, the merchant has to go through the browser authorization flow again. The id_token lifetime is set by the application configuration in Auth0.

Step 5 — Use both tokens on every request

HeaderValuePurpose
X-AuthorizationBearer <integrator JWT>Identifies your integration
Authorization-PartnersBearer <merchant id_token>Grants access to the merchant's stores

Test without a real merchant account (Development only)

In Development you do not need a real merchant account. In the Self Onboarding module:

  1. Under Sandbox merchant (test user), enter an email and a password used only for testing, and click Create test user.
  2. Under Test stores, click Create test stores. Test stores are associated with that user so you can try provisioning without asking your TAM for them.
  3. In the OAuth flow, log in as the merchant with that email and password.

Step-by-Step Flow

Step 1 — Configure the webhook (once)

Register a webhook URL for your integration so Rappi can notify you when a provisioning operation completes. This is a one-time setup per integration.

Use the POST /clients/{clientId}/webhooks endpoint:

POST /clients/{clientId}/webhooks

Request body:

{ "event": "STORE_PROVISIONING_STATUS", "url": "https://your-endpoint.com/rappi/events", "secret": "your-hmac-secret" }

The event field specifies which event to configure (currently only STORE_PROVISIONING_STATUS is supported). The secret field is optional. If provided, Rappi will sign each webhook payload with HMAC-SHA256 and include the signature in the Rappi-Signature header so you can verify the request origin. If omitted, no signature will be sent — provide your own secret and store it securely if you need to verify webhook authenticity.

A 201 Created response confirms the webhook is configured (or 200 OK if updating an existing configuration). From this point on, all provisioning and deprovisioning results for your integration will be delivered to this URL.

Step 2 — Retrieve Stores

Before provisioning, verify which stores are already integrated and which are not. This avoids duplicate provisioning requests.

Use the GET /stores/integration-status endpoint:

GET /stores/integration-status

Headers:

HeaderValue
X-AuthorizationBearer <integrator JWT> (M2M, Auth0)
Authorization-PartnersBearer <merchant id_token> (OIDC, Auth0)

The store IDs are fetched automatically from the merchant's JWT email — no request body is needed.

Response:

{ "stores": [ { "store_id": "1", "name": "Your Brand Main", "brand": "YourBrand", "integrated": true, "integration_id": "your-integration-id", "children": [ { "store_id": "3", "name": "Child Store 3", "brand": "YourBrand", "integrated": true, "integration_id": "your-integration-id" }, { "store_id": "4", "name": "Child Store 4", "brand": "YourBrand", "integrated": false } ] }, { "store_id": "2", "name": "Your Brand Secondary", "brand": "YourBrand", "integrated": true, "integration_id": "your-integration-id", "children": [] }, { "store_id": "10", "name": "Sertester1", "brand": "YourBrand", "integrated": false, "children": [ { "store_id": "20", "name": "Sertester1 Child 1", "brand": "YourBrand", "integrated": false }, { "store_id": "21", "name": "Sertester1 Child 2", "brand": "YourBrand", "integrated": false } ] }, { "store_id": "11", "name": "FIFOUno", "brand": "YourBrand", "integrated": false, "children": [] } ] }

Proceed to provision only the stores where integrated is false. Each entry includes store_id, name, and brand to help you identify the store. The children array in the GET response reflects the current Rappi hierarchy — when provisioning via POST, you can send parent_store_id to integrate a store as a child of another store of your integration; without it, a store that is already a child is promoted to a standalone parent unless you send keep_hierarchy: true.

Step 3 — Activation

Submit a provisioning request for the stores that are not yet integrated. This operation is asynchronous — the API returns 202 Accepted immediately and the result is delivered via webhook. You can provision up to 20 stores per request.

Use the POST /stores/provisioning endpoint:

POST /stores/provisioning

Headers:

HeaderValue
X-AuthorizationBearer <integrator JWT> (M2M, Auth0)
Authorization-PartnersBearer <merchant id_token> (OIDC, Auth0)

Request body:

{ "stores": [ { "store_id": "10", "name": "My Store", "status": "ACTIVE", "store_integration_id": "POS-001" }, { "store_id": "101", "name": "North Branch", "status": "ACTIVE", "parent_store_id": "10", "store_integration_id": "POS-NORTH" }, { "store_id": "11", "name": "My Other Store", "status": "ACTIVE", "keep_hierarchy": false } ] }

Fields of each item

  • store_id and name are required.
  • status is optional. If it is not sent, it defaults to ACTIVE.

Store hierarchy

The hierarchy is defined per store and supports a maximum of two levels (parent and child).

Assign a parent. If you send parent_store_id, the store is created as a child of that store. The parent store must meet three conditions:

  • belong to the same merchant,
  • be already integrated in your integration,
  • not be a child of another store.

If you omit parent_store_id and the store is already a child, by default it becomes an independent parent store (keep_hierarchy is false). If you want it to keep its current parent, send keep_hierarchy: true.

Change the parent. To move a store that is already a child of a different parent, send the new parent_store_id. Do not combine it with keep_hierarchy: true, because the request will be rejected with the keep_hierarchy_conflict error.

If you resend the same parent the store already has, the operation is idempotent and nothing changes.

Restrictions

  • A store with open orders cannot change its hierarchy: it is rejected with has_open_orders (see the rejection reasons of POST /stores/provisioning in the API reference).

Provisioning rules:

RuleDescription
R1All stores must belong to the authenticated merchant.
R2If a store is already integrated with the same integration, provisioning is idempotent (no changes are made).
R3A store with integrated child stores cannot be deprovisioned — it will be rejected with has_integrated_children. Deprovision all child stores first.

The following fields are optional and control integration behavior:

FieldTypeDefaultDescription
store_integration_idstringRappi store_idYour internal store identifier (Store ID at POS). Use this to map the Rappi store to your own system.
ping_activebooleantrueEnable ping events
get_menu_activebooleantrueEnable get-menu events
cancellation_eventsbooleantrueEnable cancellation events
other_eventsbooleantrueEnable other order events (ready, status changes) besides cancellation

Response: 202 Accepted

{ "batch_id": "550e8400-e29b-41d4-a716-446655440000", "accepted": [ { "store_id": "10", "integration_id": "your-integration-id" }, { "store_id": "101", "integration_id": "your-integration-id" } ], "rejected": [{ "store_id": "11", "reason": "not_owned" }] }

Possible rejected[].reason values:

ReasonMeaning
not_ownedThe store does not belong to the authenticated merchant.
missing_nameThe name field is missing or blank.
invalid_statusThe status field has an invalid value.

If all stores are rejected (none owned by the merchant), the API returns 422 Unprocessable Entity.

Step 4 — Receive the webhook

When the provisioning operation completes, Rappi sends a STORE_PROVISIONING_STATUS event to the URL configured in step 1.

See STORE_PROVISIONING_STATUS for the full payload reference.

Example payload:

{ "batchId": "550e8400-e29b-41d4-a716-446655440000", "integrationId": "your-integration-id", "operation": "PROVISION", "results": [ { "storeId": "10", "integrationId": "your-integration-id", "brand": "YourBrand", "status": "ACTIVE", "httpCode": 201 }, { "storeId": "101", "integrationId": "your-integration-id", "brand": "YourBrand", "status": "ACTIVE", "httpCode": 201 }, { "storeId": "11", "integrationId": "your-integration-id", "brand": "YourBrand", "status": "FAILED", "errorMessage": "Store already exists", "httpCode": 409 } ], "timestamp": "2026-04-21T10:00:00Z" }

Possible results[].status values:

StatusMeaning
ACTIVEProvisioning completed successfully. The store is now integrated.
INACTIVEDeprovisioning completed successfully.
FAILEDThe operation failed. Check errorMessage and httpCode for details.

results[].httpCode is the HTTP status code of the underlying operation (e.g. 201 for success, 409 for conflict, 204 for deprovisioning).

operation is either PROVISION or DEPROVISION.

Step 5 — Deactivating (optional)

To remove stores from your integration, use the POST /stores/deprovisioning endpoint. Like provisioning, this is asynchronous — the result is delivered via the same STORE_PROVISIONING_STATUS webhook with operation: DEPROVISION and status: INACTIVE per store.

POST /stores/deprovisioning

Headers:

HeaderValue
X-AuthorizationBearer <integrator JWT> (M2M, Auth0)
Authorization-PartnersBearer <merchant id_token> (OIDC, Auth0)

Request body:

{ "stores": [{ "store_id": "10" }] }

The store_id field is required per store item.

Possible rejected[].reason values:

ReasonMeaning
not_integratedThe store is not currently integrated.

Response: 202 Accepted with the same batch body as provisioning.

If all stores are rejected, the API returns 422 Unprocessable Entity.

Full Flow Summary

[Once] Configure webhook → POST /clients/{clientId}/webhooks [Per batch] Retrieve Stores → GET /stores/integration-status Activation → POST /stores/provisioning (up to 20 stores per request) Await result → STORE_PROVISIONING_STATUS webhook [Optional] Deactivating → POST /stores/deprovisioning

Error Response Format

All error responses from this API use a consistent JSON structure:

{ "message": "Human-readable description of the error" }

HTTP Status Codes

StatusWhen
400 Bad RequestInvalid request — missing fields, empty list, exceeds 20 stores, mixed integrations in batch
401 UnauthorizedMissing or invalid integrator token
403 ForbiddenMerchant token does not match the integration's integrationId, or merchant not authorized in Partners
422 Unprocessable EntityAll stores were rejected (none owned by the merchant)
424 Failed DependencyPartners service is unavailable
500 Internal Server ErrorUnexpected server error

Example — exceeding the store limit:

HTTP/1.1 400 Bad Request { "message": "stores list exceeds maximum allowed size of 20" }

Example — merchant not authorized:

HTTP/1.1 403 Forbidden { "message": "Merchant not authorized in Partners" }