Partner Authentication

Partners hold two different kinds of credentials, and they are not interchangeable:

Credential	What it is	What it authorizes
`X-API-Key` + `X-API-Secret`	Your partner platform credentials	The `/v1/partners/*` endpoints — your merchant list, your webhook config, your analytics
`merchant-key`	A per-merchant key delivered to you in `store_onboarded`	Payment operations for that merchant — orders, links, order status

The rule: partner credentials manage your platform; merchant keys move money.

Partner platform requests

Send both partner headers, and nothing else:

curl "https://api.wava.co/v1/partners/stores" \
  -H "X-API-Key: YOUR_PARTNER_API_KEY" \
  -H "X-API-Secret: YOUR_PARTNER_SECRET_KEY"

Wava validates that the key/secret pair belongs to an active integration and that the store behind it is flagged as a partner. The store the credentials resolve to is your own partner store — that is what scopes the response to your merchants. Failure modes:

Response	Cause
`401` `INVALID_API_CREDENTIALS`	Key/secret pair not recognized
`403` `NOT_A_PARTNER`	The account behind the credentials is not a partner platform
`500` `PARTNER_NAME_NOT_FOUND`	Partner account exists but has no partner name configured — contact support

Requests on behalf of a merchant

Order and payment-link endpoints are authorized by the merchant’s key. Send merchant-key alone:

curl -X POST "https://api.wava.co/v1/orders" \
  -H "merchant-key: MERCHANT_KEY_FROM_STORE_ONBOARDED" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Wava resolves the store from the merchant key, and the resulting order belongs to that merchant. Your partner relationship is what routes the order’s webhooks back to you — it does not need to be re-asserted on the request. You may also send your X-API-Key and X-API-Secret alongside the merchant key. They are treated as attribution only — they identify the request as coming from your platform and never change which store the operation lands on. The merchant key alone decides that.

Partner credentials on their own are not enough on these endpoints. A request carrying X-API-Key/X-API-Secret without a valid merchant-key is rejected with 403 UNAUTHORIZED_ACCESS — the partner credentials never select a store for you.

Which headers go where

Endpoint	`X-API-Key` + `X-API-Secret`	`merchant-key`
`GET /v1/partners/stores`	Required	Do not send
`POST /v1/partners/stores/{storeId}/deactivate`	Required	Do not send
`GET` / `PATCH /v1/partners/webhook`	Required	Do not send
`POST /v1/partners/webhook/test`	Required	Do not send
`GET /v1/partners/events`	Required	Do not send
`GET /v1/partners/analytics/*`	Required	Do not send
`POST /v1/orders`	Optional (attribution)	Required
`POST /v1/links`	Optional (attribution)	Required
`GET /v1/orders/{orderId}`	Optional (attribution)	Required

On the /v1/partners/* endpoints the partner credentials are what authorize the call, and no merchant key is involved. On the payment endpoints it is the reverse: the merchant key authorizes, and the partner credentials are optional metadata.

Handling credentials

Both partner values are issued once, when Wava creates your partner account, and cannot be retrieved afterwards.
Keep them server-side. They authorize access to every merchant connected to your platform.
Merchant keys are per-merchant secrets. Store them encrypted, scoped to the merchant they belong to, and never expose one merchant’s key to another merchant’s session.
To rotate any of these, contact soporte@wava.co.

Getting Started

Orders

Payment Flows

Payment Links

Partners

Webhooks

Integrations

Testing

Error Handling

Partner Authentication

Partner Authentication

Partner platform requests

Requests on behalf of a merchant

Which headers go where

Handling credentials

​Partner Authentication

​Partner platform requests

​Requests on behalf of a merchant

​Which headers go where

​Handling credentials

Partner Authentication

Partner platform requests

Requests on behalf of a merchant

Which headers go where

Handling credentials