Merchant API

Endpoints

Method	Path	Scope	Description
GET	/v1/merchant/me	merchant:read	Get profile
PUT	/v1/merchant/webhook	merchant:write	Set webhook URL
PUT	/v1/merchant/providers	merchant:write	Set provider credentials
GET	/v1/merchant/providers	merchant:read	List providers (masked)
DELETE	/v1/merchant/providers/{provider}	merchant:write	Remove provider

Get Profile

GET /v1/merchant/me
X-API-Key: sk_live_...

{
  "success": true,
  "data": {
    "id": "merchant-uuid-...",
    "name": "Acme Corp",
    "role": "merchant",
    "webhook_url": "https://acme.com/webhooks",
    "has_webhook_secret": true,
    "is_active": true,
    "providers": ["stripe", "mpesa"]
  }
}

Set Webhook URL

PUT /v1/merchant/webhook
X-API-Key: sk_live_...

{
  "webhook_url": "https://acme.com/webhooks"
}

Response

{
  "success": true,
  "data": {
    "webhook_url": "https://acme.com/webhooks",
    "webhook_secret": "whsec_a1b2c3..."
  }
}

Secret shown once

The webhook_secret is returned only in this response. Save it immediately. Calling this endpoint again rotates the secret.

Set Provider Credentials

See Provider Setup for full details on each provider's fields.

List Providers

GET /v1/merchant/providers
X-API-Key: sk_live_...

{
  "success": true,
  "data": [
    {
      "id": "config-uuid-...",
      "provider": "stripe",
      "is_active": true,
      "config_summary": {
        "secret_key": "****4x7K",
        "webhook_secret": "****test"
      },
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-01-01T00:00:00Z"
    }
  ]
}

Remove Provider

DELETE /v1/merchant/providers/stripe
X-API-Key: sk_live_...

{ "success": true }