Onboard Merchant

August 3, 2026 ยท View on GitHub

Use case

Creates a merchant workspace from the authenticated dashboard flow.

Authentication

Dashboard protected. Send Authorization: Bearer <jwt_token>. In sandbox, also send x-feature: decision-engine.

For local development, start with:

export BASE_URL=http://localhost:8080
export AUTH_HEADER="Authorization: Bearer <jwt_token>"
# Sandbox only:
# export BASE_URL=https://sandbox.hyperswitch.io
# export FEATURE_HEADER="x-feature: decision-engine"

Request

  • Method and path: POST /onboarding/merchant
  • Parameters: none.
  • Body: JSON body with merchant_name.

Example

Onboard merchant

curl --location "$BASE_URL/onboarding/merchant" \
  --header "$AUTH_HEADER" \
  --header "Content-Type: application/json" \
  --data '{
  "merchant_name": "Demo Merchant"
}'

Response

{
  "token": "eyJ...",
  "merchant_id": "merchant_9f21a6c0",
  "merchant_name": "Demo Merchant",
  "merchants": [
    { "merchant_id": "merchant_demo", "merchant_name": "Demo Merchant", "role": "admin" },
    { "merchant_id": "merchant_9f21a6c0", "merchant_name": "Demo Merchant", "role": "admin" }
  ]
}

Notes

  • This is the dashboard onboarding route. Service integrations can use /merchant-account/create directly.
  • After onboarding, switch into the merchant before configuring routing.