Merchant Account - Create

Create a merchant account with merchant details.

Endpoint

• POST /v2/merchant-accounts

Try it on the API: https://sandbox.hyperswitch.io/v2/merchant-accounts

Example (cURL)

Create merchant account (cURL)

curl --request POST \
  --url https://sandbox.hyperswitch.io/v2/merchant-accounts \
  --header 'Content-Type: application/json' \
  --header 'X-Organization-Id: <x-organization-id>' \
  --header 'api-key: <api-key>' \
  --data '
{
  "merchant_details": {
    "primary_contact_person": "John Doe",
    "primary_email": "[email protected]"
  },
  "merchant_name": "Cloth Store"
}
'

Successful response (200):

Response (application/json)

{
  "id": "y3oqhf46pyzuxjbcn2giaqnb44",
  "merchant_name": "NewAge Retailer",
  "publishable_key": "AH3423bkjbkjdsfbkj",
  "organization_id": "org_q98uSGAYbjEwqs0mJwnz",
  "recon_status": "not_requested",
  "merchant_details": {
    "primary_contact_person": "John Doe",
    "primary_phone": "999999999",
    "primary_email": "[email protected]",
    "secondary_contact_person": "John Doe2",
    "secondary_phone": "999999988",
    "secondary_email": "[email protected]",
    "website": "www.example.com",
    "about_business": "Online Retail with a wide selection of organic products for North America",
    "address": {
      "city": "New York",
      "country": "AF",
      "line1": "123, King Street",
      "line2": "Powelson Avenue",
      "line3": "Bridgewater",
      "zip": "08807",
      "state": "New York",
      "first_name": "John",
      "last_name": "Doe",
      "origin_zip": "08807"
    },
    "merchant_tax_registration_id": "123456789"
  },
  "metadata": {},
  "product_type": "orchestration"
}

---

Authorizations

• api-key (header, string) — required Admin API keys allow you to perform some privileged actions such as creating a merchant account and Connector account.

Use an Admin API key in the api-key header to create merchant accounts.

Headers

• Content-Type: application/json

• X-Organization-Id (string) — required Organization ID for which the merchant account has to be created.

• api-key (string) — required

Body (application/json)

Fields:

• merchant_name (string) — required Name of the Merchant Account. This will be used as a prefix to generate the id. Maximum length: 64 Example: "NewAge Retailer"

• merchant_details (object) — optional Object containing merchant contact and business details. See example above for common attributes (primary_contact_person, primary_email, primary_phone, website, about_business, address, merchant_tax_registration_id, etc.).

• metadata (object) — optional Metadata is useful for storing additional, unstructured information about the merchant account.

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

---

Response (200 — application/json)

Merchant Account Created. Fields:

• id (string) — required Identifier for the Merchant Account. Example: "y3oqhf46pyzuxjbcn2giaqnb44"

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

• publishable_key (string) — required API key that will be used for server side API access. Example: "AH3423bkjbkjdsfbkj"

• organization_id (string) — required The id of the organization which the merchant is associated with. Example: "org_q98uSGAYbjEwqs0mJwnz"

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

• merchant_details (object) — may contain contact, address, tax id, etc. See response example above.

• metadata (object) — optional

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

---

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