> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wava.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Onboarding Merchants

> How merchants reach Wava through your link and how you receive them.

# Onboarding Merchants

This page walks the complete path a merchant takes from your platform into Wava, and what you receive at each point. It is the flow behind the `store_onboarded` webhook.

## 1. Your onboarding link

Wava issues you an onboarding link when your partner account is created, together with your production credentials. It is the Wava signup page carrying your partner name in the `platform` query parameter:

```
https://app.wava.co/signup?platform=YourPartnerName
```

`YourPartnerName` is the partner name registered on your account — the same name Wava uses to resolve your integration. It is fixed at account creation; you do not choose it per merchant.

This is the same mechanism the Tiendanube and WooCommerce integrations use, and it is what drives the automatic connection in step 2. There is nothing to configure on your side beyond putting the link in front of your merchants — in your onboarding emails, your dashboard, your setup wizard.

<Note>
  The link is per-partner, not per-merchant. You do not generate a new link per merchant and you do not pre-register merchants with Wava.
</Note>

### Passing your own merchant ID

Add `eid` to carry your internal identifier for that merchant:

```
https://app.wava.co/signup?platform=YourPartnerName&eid=your-internal-merchant-id
```

It is stored on the Wava store as `external_store_id` and comes back to you in every webhook — as `external_id` in `store_onboarded` and as `external_store_id` in order events — so you can match events to your own records without keeping a lookup table.

Generate the link per merchant from your own system if you want this. It is optional: without it the field arrives as `null` and you match on `id_store`, which is always present.

<Note>
  `eid` is a single reference string (up to 80 characters), not an arbitrary metadata object. Use it for your own merchant or account ID.
</Note>

## 2. The merchant signs up — the integration is automatic

The merchant follows the link, creates their Wava account and completes onboarding (business details, documents, payout account).

As soon as onboarding finishes and the store becomes active, Wava reads the `platform` value carried from the link, resolves it to your partner account, and **creates the integration automatically**. The merchant does not have to find your platform in a settings screen.

The integration created on the merchant's store is:

* `platform`: your partner name (e.g. `Mercately`)
* `platform_type`: `partner`
* `allowed_scopes`: copied from your partner account, so the merchant is operated with exactly the permissions you were approved for
* `external_store_id`: the `eid` from the link, if you passed one

Under the hood this is a single call made on the merchant's behalf once their store leaves `draft`:

```http theme={null}
POST /v1/stores/{storeId}/integrations
x-auth-token: <merchant session>
Content-Type: application/json

{
  "platform": "YourPartnerName",
  "external_store_id": "your-internal-merchant-id"
}
```

<Note>
  Your `X-API-Key`/`X-API-Secret` are not involved here and cannot be used to connect a merchant to you. The link is the mechanism.
</Note>

### Re-subscribing

A merchant can go through your link again — after you or they disconnected, or simply to refresh the connection. Every time they do, the integration is brought back to active, the `eid` on the link is written to the store, and you receive `store_onboarded` again.

<Warning>
  `store_onboarded` is therefore **not** a once-per-merchant event. Key your handler on `id_store` and make it idempotent: treat a repeat as "this merchant is (still) connected, here is the current merchant key" rather than as a new signup.
</Warning>

## 3. You receive `store_onboarded`

The moment the integration is created, Wava POSTs `store_onboarded` to the webhook URL configured on your partner account. This is the event that hands you a merchant you can start charging for.

```json theme={null}
{
  "event": "store_onboarded",
  "timestamp": "2026-08-06T14:22:31.004Z",
  "id_store": 2841,
  "external_id": "your-internal-merchant-id",
  "store_name": "Café Bogotá",
  "store_url": "https://cafebogota.co",
  "status": "active",
  "merchant_key": "mk_live_9f2c7a1e4b8d6350a1c9",
  "country": "Colombia",
  "currency": "COP",
  "referred_by": null
}
```

| Field                      | Meaning                                                                                                                                                                                                                                              |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id_store`                 | Wava's ID for this merchant. Use it on `/v1/partners/*` endpoints.                                                                                                                                                                                   |
| `external_id`              | The `eid` you put on the onboarding link, stored as the store's `external_store_id`. `null` if you did not pass one.                                                                                                                                 |
| `store_name` / `store_url` | The merchant's business name and site.                                                                                                                                                                                                               |
| `status`                   | Store status at the time of the event.                                                                                                                                                                                                               |
| `merchant_key`             | **The credential you store.** It authorizes order and link creation for this merchant.                                                                                                                                                               |
| `country`                  | Country name of the store (e.g. `Colombia`).                                                                                                                                                                                                         |
| `currency`                 | The store's default currency (ISO 4217).                                                                                                                                                                                                             |
| `referred_by`              | Store ID from Wava's separate store-referral program, unrelated to the partner link. Normally `null` for merchants onboarded through your `platform` link. Your relationship with the merchant is established by the integration, not by this field. |

Request headers on that POST:

```
Content-Type: application/json
X-Wava-Event: store_onboarded
X-Wava-Timestamp: 2026-08-06T14:22:31.004Z
X-Wava-Signature: 6f1a9c...        # present when signing is enabled
User-Agent: Wava-Webhooks/1.0
```

Verify the signature before trusting the payload — see [Webhook Security](/webhooks/security).

<Warning>
  `store_onboarded` is only delivered if `store_onboarded` is present in your subscribed `events` list. Check it with `GET /v1/partners/webhook`. If your webhook URL is not configured, or the event is not subscribed, the merchant is still connected to you — you simply never hear about it. Reconcile with `GET /v1/partners/stores`.
</Warning>

## 4. You store the merchant key and start processing

Persist `id_store` and `merchant_key` against your own merchant record. From then on:

```bash theme={null}
curl -X POST "https://api.wava.co/v1/orders" \
  -H "merchant-key: mk_live_9f2c7a1e4b8d6350a1c9" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50000,
    "currency": "COP",
    "description": "Product purchase",
    "order_key": "your-order-001"
  }'
```

See [Creating Orders](/partners/creating-orders) and [Creating Links](/partners/creating-links) for the full request bodies, and [Partner Authentication](/partners/authentication) for the header rules.

## 5. Payment events come back to you

Once an order for that merchant is paid, Wava sends `order_payment` to **your** webhook URL — the same URL that received `store_onboarded` — because the merchant's store carries your partner integration. Payment-link orders created via the API also emit `link_paid`.

You receive these for every merchant connected to you. Use `id_store` (or `external_store_id`) in the payload to route the event to the right merchant on your side.

See [Partner Webhooks](/partners/webhooks) for the payloads.

## 6. Disconnecting

Either side can end the relationship:

* **You:** `POST /v1/partners/stores/{storeId}/deactivate` deactivates your integration on that merchant's store.
* **The merchant:** deactivating your integration from their dashboard.

After deactivation the store stops appearing in `GET /v1/partners/stores`, and its events stop reaching your webhook URL. The merchant's Wava account and its merchant key continue to exist — they are simply no longer yours to operate.

The relationship can be re-established at any time by sending the merchant through your onboarding link again, which brings the integration back and re-delivers `store_onboarded`.

## Reconciling

`store_onboarded` is a notification, not a ledger. Treat `GET /v1/partners/stores` as the source of truth for who is connected to you, and reconcile against it periodically to catch merchants who connected while your endpoint was down.

<Warning>
  `GET /v1/partners/stores` does **not** return merchant keys — `store_onboarded` is the only place a merchant key is delivered to you, so persist it when the webhook arrives. If you lose it, sending the merchant through your onboarding link again re-delivers it; otherwise contact [soporte@wava.co](mailto:soporte@wava.co).
</Warning>