Merchant Account - Create

POST /accounts

Create a merchant account with minimal fields.

Request

Headers

  • Content-Type: application/json

  • api-key: (required) Admin API keys allow privileged actions such as creating a merchant account and Merchant Connector account.

Body (application/json) — example minimal payload:

request.json
{
  "sub_merchants_enabled": false,
  "enable_payment_response_hash": false,
  "redirect_to_merchant_with_http_post": false
}

cURL example:

curl
curl --request POST \
  --url https://sandbox.hyperswitch.io/accounts \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '
{
  "sub_merchants_enabled": false,
  "enable_payment_response_hash": false,
  "redirect_to_merchant_with_http_post": false
}
'

Request Body fields (selected)

  • merchant_id (string, required) The identifier for the Merchant Account. Required string length: 1 - 64. Example: "y3oqhf46pyzuxjbcn2giaqnb44"

  • merchant_name (string | null) Name of the Merchant Account. Example: "NewAge Retailer"

  • merchant_details (object) See child attributes in the API reference for full structure.

  • return_url (string | null) The URL to redirect after the completion of the operation. Maximum length: 255. Example: "https://www.example.com/success"

  • webhook_details (object) See child attributes in the API reference for full structure.

  • payout_routing_algorithm (object) See child attributes in the API reference for full structure.

  • sub_merchants_enabled (boolean | null, default: false) Indicates if the merchant is a sub-merchant under a parent merchant. Example: false

  • parent_merchant_id (string | null) Parent Merchant ID when creating a sub-merchant. Max length: 255. Example: "xkkdf909012sdjki2dkh5sdf"

  • enable_payment_response_hash (boolean | null, default: false) Indicates if payment response hash should be enabled. Example: true

  • payment_response_hash_key (string | null) Hash key used for webhook/redirect signatures. If omitted, a value is auto-generated.

  • redirect_to_merchant_with_http_post (boolean | null, default: false) Indicates if redirect to merchant with HTTP POST should be enabled. Example: true

  • metadata (object) Unstructured metadata.

  • publishable_key (string | null) API key used for client-side access. Example: "AH3423bkjbkjdsfbkj"

  • locker_id (string | null) Identifier for vault storing payment method information. Example: "locker_abc123"

  • primary_business_details (object) See child attributes in the API reference.

  • frm_routing_algorithm (object) FRM routing algorithm details.

  • organization_id (string | null) Organization id the merchant belongs to; if not passed, an organization is created. Required string length: 1 - 64. Example: "org_q98uSGAYbjEwqs0mJwnz"

  • pm_collect_link_config (object) GenericLinkUiConfig object; see child attributes.

  • product_type (enum) Available: orchestration, vault, recon, recovery, cost_observability, dynamic_routing

  • merchant_account_type (enum) Available: standard, connected

(For full schema and all child attributes, refer to the API reference.)

Response

Status: 200 application/json Merchant Account Created — example:

Response fields (selected)

  • merchant_id (string, required) The identifier for the Merchant Account. Max length: 64. Example: "y3oqhf46pyzuxjbcn2giaqnb44"

  • enable_payment_response_hash (boolean, required, default: false) Example: true

  • redirect_to_merchant_with_http_post (boolean, required, default: false) Example: true

  • primary_business_details (object[]) (required) Details about the primary business unit.

  • organization_id (string, required) Organization id merchant is associated with. Required length: 1 - 64. Example: "org_q98uSGAYbjEwqs0mJwnz"

  • is_recon_enabled (boolean, required) Whether recon service is enabled.

  • recon_status (enum, required) Available: not_requested, requested, active, disabled

  • merchant_account_type (enum, required) Available: standard, platform, connected

  • merchant_name (string | null) Example: "NewAge Retailer"

  • return_url (string | null) Maximum length: 255. Example: "https://www.example.com/success"

  • payment_response_hash_key (string | null) Max length: 255. Example: "xkkdf909012sdjki2dkh5sdf"

  • merchant_details (object) See child attributes.

  • webhook_details (object) See child attributes.

  • payout_routing_algorithm (object) See child attributes.

  • sub_merchants_enabled (boolean | null, default: false) Example: false

  • parent_merchant_id (string | null) Example: "xkkdf909012sdjki2dkh5sdf"

  • publishable_key (string | null) Example: "AH3423bkjbkjdsfbkj"

  • metadata (object) Unstructured information.

  • locker_id (string | null) Example: "locker_abc123"

  • frm_routing_algorithm (object) See child attributes.

  • default_profile (string | null) Default profile used for creating accounts/payments. Max length: 64.

  • pm_collect_link_config (object) GenericLinkUiConfig object; see child attributes.

  • product_type (enum) Available: orchestration, vault, recon, recovery, cost_observability, dynamic_routing

Suggest edits: https://github.com/juspay/hyperswitch/edit/main/api-reference/v1/merchant-account/merchant-account--create.mdx Raise issue: https://github.com/juspay/hyperswitch/issues/new?title=Issue%20on%20docs&body=Path:%20/v1/merchant-account/merchant-account--create

PreviousPayment Method Session - CreateNextMerchant Account - KV Status