Skip to main content

​
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. 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:
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.
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.

​
Passing your own merchant ID

Add eid to carry your internal identifier for that merchant:
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.
eid is a single reference string (up to 80 characters), not an arbitrary metadata object. Use it for your own merchant or account ID.

​
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:
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.

​
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.
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.

​
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.
Request headers on that POST:
Verify the signature before trusting the payload — see Webhook Security.
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.

​
4. You store the merchant key and start processing

Persist id_store and merchant_key against your own merchant record. From then on:
See Creating Orders and Creating Links for the full request bodies, and Partner 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 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.
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.