Merchant Account - Create

POST

accounts

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

{
  "merchant_id": "y3oqhf46pyzuxjbcn2giaqnb44",
  "merchant_name": "NewAge Retailer",
  "return_url": "https://www.example.com/success",
  "enable_payment_response_hash": true,
  "payment_response_hash_key": "xkkdf909012sdjki2dkh5sdf",
  "redirect_to_merchant_with_http_post": true,
  "merchant_details": {
    "primary_contact_person": "John Doe",
    "primary_phone": "999999999",
    "primary_email": "johndoe@test.com",
    "secondary_contact_person": "John Doe2",
    "secondary_phone": "999999988",
    "secondary_email": "johndoe2@test.com",
    "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"
    }
  },
  "webhook_details": {
    "webhook_version": "1.0.2",
    "webhook_username": "ekart_retail",
    "webhook_password": "ekart@123",
    "webhook_url": "www.ekart.com/webhooks",
    "payment_created_enabled": true,
    "payment_succeeded_enabled": true,
    "payment_failed_enabled": true
  },
  "payout_routing_algorithm": {
    "type": "single",
    "data": {
      "connector": "adyenplatform",
      "merchant_connector_id": "<string>"
    }
  },
  "sub_merchants_enabled": false,
  "parent_merchant_id": "xkkdf909012sdjki2dkh5sdf",
  "publishable_key": "AH3423bkjbkjdsfbkj",
  "metadata": {},
  "locker_id": "locker_abc123",
  "primary_business_details": [
    {
      "country": "AF",
      "business": "food"
    }
  ],
  "frm_routing_algorithm": {
    "type": "single",
    "data": {
      "connector": "adyenplatform",
      "merchant_connector_id": "<string>"
    }
  },
  "organization_id": "org_q98uSGAYbjEwqs0mJwnz",
  "is_recon_enabled": true,
  "default_profile": "<string>",
  "recon_status": "not_requested",
  "pm_collect_link_config": {
    "logo": "https://hyperswitch.io/favicon.ico",
    "merchant_name": "Hyperswitch",
    "theme": "#4285F4",
    "domain_name": "<string>",
    "allowed_domains": [
      "<string>"
    ],
    "enabled_payment_methods": "[{\"payment_method\": \"bank_transfer\", \"payment_method_types\": [\"ach\", \"bacs\", \"sepa\"]}]"
  }
}

Authorizations

api-key

string

header

required

Admin API keys allow you to perform some privileged actions such as creating a merchant account and Merchant Connector account.

Body

application/json

merchant_id

string

required

The identifier for the Merchant Account

Required string length: 1 - 64

merchant_name

string | null

Name of the Merchant Account

merchant_details

object

merchant_details.primary_contact_person

string | null

The merchant's primary contact name

Maximum length: 255

merchant_details.primary_phone

string | null

The merchant's primary phone number

Maximum length: 255

merchant_details.primary_email

string | null

The merchant's primary email address

Maximum length: 255

merchant_details.secondary_contact_person

string | null

The merchant's secondary contact name

Maximum length: 255

merchant_details.secondary_phone

string | null

The merchant's secondary phone number

Maximum length: 255

merchant_details.secondary_email

string | null

The merchant's secondary email address

Maximum length: 255

merchant_details.website

string | null

The business website of the merchant

Maximum length: 255

merchant_details.about_business

string | null

A brief description about merchant's business

Maximum length: 255

merchant_details.address

object

Address details

return_url

string | null

The URL to redirect after the completion of the operation

Maximum length: 255

webhook_details

object

payout_routing_algorithm

object

Routing Algorithm kind

sub_merchants_enabled

boolean | null

default:

false

A boolean value to indicate if the merchant is a sub-merchant under a master or a parent merchant. By default, its value is false.

parent_merchant_id

string | null

Refers to the Parent Merchant ID if the merchant being created is a sub-merchant

Maximum length: 255

enable_payment_response_hash

boolean | null

default:

false

A boolean value to indicate if payment response hash needs to be enabled

payment_response_hash_key

string | null

Refers to the hash key used for calculating the signature for webhooks and redirect response. If the value is not provided, a value is automatically generated.

redirect_to_merchant_with_http_post

boolean | null

default:

false

A boolean value to indicate if redirect to merchant with http post needs to be enabled.

metadata

object | null

Metadata is useful for storing additional, unstructured information on an object

publishable_key

string | null

API key that will be used for client side API access. A publishable key has to be always paired with a client_secret. A client_secret can be obtained by creating a payment with confirm set to false

locker_id

string | null

An identifier for the vault used to store payment method information.

primary_business_details

object

frm_routing_algorithm

object | null

The frm routing algorithm to be used for routing payments to desired FRM's

organization_id

string | null

The id of the organization to which the merchant belongs to, if not passed an organization is created

Required string length: 1 - 64

pm_collect_link_config

object

Object for GenericLinkUiConfig

pm_collect_link_config.allowed_domains

string[]

required

A list of allowed domains (glob patterns) where this link can be embedded / opened from

pm_collect_link_config.enabled_payment_methods

object[]

required

List of payment methods shown on collect UI

pm_collect_link_config.logo

string | null

Merchant's display logo

Maximum length: 255

pm_collect_link_config.merchant_name

string | null

Custom merchant name for the link

Maximum length: 255

pm_collect_link_config.theme

string | null

Primary color to be used in the form represented in hex format

Maximum length: 255

pm_collect_link_config.domain_name

string | null

Custom domain name to be used for hosting the link

Response

200

application/json

Merchant Account Created

merchant_id

string

required

The identifier for the Merchant Account

Maximum length: 64

enable_payment_response_hash

boolean

default:

false

required

A boolean value to indicate if payment response hash needs to be enabled

redirect_to_merchant_with_http_post

boolean

default:

false

required

A boolean value to indicate if redirect to merchant with http post needs to be enabled

primary_business_details

object[]

required

Details about the primary business unit of the merchant account

organization_id

string

required

The organization id merchant is associated with

Required string length: 1 - 64

is_recon_enabled

boolean

required

A boolean value to indicate if the merchant has recon service is enabled or not, by default value is false

recon_status

enum<string>

required

Available options:

not_requested,

requested,

active,

disabled

merchant_name

string | null

Name of the Merchant Account

return_url

string | null

The URL to redirect after completion of the payment

Maximum length: 255

payment_response_hash_key

string | null

Refers to the hash key used for calculating the signature for webhooks and redirect response. If the value is not provided, a value is automatically generated.

Maximum length: 255

merchant_details

object

merchant_details.primary_contact_person

string | null

The merchant's primary contact name

Maximum length: 255

merchant_details.primary_phone

string | null

The merchant's primary phone number

Maximum length: 255

merchant_details.primary_email

string | null

The merchant's primary email address

Maximum length: 255

merchant_details.secondary_contact_person

string | null

The merchant's secondary contact name

Maximum length: 255

merchant_details.secondary_phone

string | null

The merchant's secondary phone number

Maximum length: 255

merchant_details.secondary_email

string | null

The merchant's secondary email address

Maximum length: 255

merchant_details.website

string | null

The business website of the merchant

Maximum length: 255

merchant_details.about_business

string | null

A brief description about merchant's business

Maximum length: 255

merchant_details.address

object

Address details

webhook_details

object

payout_routing_algorithm

object

Routing Algorithm kind

sub_merchants_enabled

boolean | null

default:

false

A boolean value to indicate if the merchant is a sub-merchant under a master or a parent merchant. By default, its value is false.

parent_merchant_id

string | null

Refers to the Parent Merchant ID if the merchant being created is a sub-merchant

Maximum length: 255

publishable_key

string | null

API key that will be used for server side API access

metadata

object | null

Metadata is useful for storing additional, unstructured information on an object.

locker_id

string | null

An identifier for the vault used to store payment method information.

frm_routing_algorithm

object

Routing Algorithm kind

default_profile

string | null

The default profile that must be used for creating merchant accounts and payments

Maximum length: 64

pm_collect_link_config

object

Object for GenericLinkUiConfig

pm_collect_link_config.allowed_domains

string[]

required

A list of allowed domains (glob patterns) where this link can be embedded / opened from

pm_collect_link_config.enabled_payment_methods

object[]

required

List of payment methods shown on collect UI

pm_collect_link_config.logo

string | null

Merchant's display logo

Maximum length: 255

pm_collect_link_config.merchant_name

string | null

Custom merchant name for the link

Maximum length: 255

pm_collect_link_config.theme

string | null

Primary color to be used in the form represented in hex format

Maximum length: 255

pm_collect_link_config.domain_name

string | null

Custom domain name to be used for hosting the link

Organization - Update Merchant Account - Retrieve

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

{
  "merchant_id": "y3oqhf46pyzuxjbcn2giaqnb44",
  "merchant_name": "NewAge Retailer",
  "return_url": "https://www.example.com/success",
  "enable_payment_response_hash": true,
  "payment_response_hash_key": "xkkdf909012sdjki2dkh5sdf",
  "redirect_to_merchant_with_http_post": true,
  "merchant_details": {
    "primary_contact_person": "John Doe",
    "primary_phone": "999999999",
    "primary_email": "johndoe@test.com",
    "secondary_contact_person": "John Doe2",
    "secondary_phone": "999999988",
    "secondary_email": "johndoe2@test.com",
    "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"
    }
  },
  "webhook_details": {
    "webhook_version": "1.0.2",
    "webhook_username": "ekart_retail",
    "webhook_password": "ekart@123",
    "webhook_url": "www.ekart.com/webhooks",
    "payment_created_enabled": true,
    "payment_succeeded_enabled": true,
    "payment_failed_enabled": true
  },
  "payout_routing_algorithm": {
    "type": "single",
    "data": {
      "connector": "adyenplatform",
      "merchant_connector_id": "<string>"
    }
  },
  "sub_merchants_enabled": false,
  "parent_merchant_id": "xkkdf909012sdjki2dkh5sdf",
  "publishable_key": "AH3423bkjbkjdsfbkj",
  "metadata": {},
  "locker_id": "locker_abc123",
  "primary_business_details": [
    {
      "country": "AF",
      "business": "food"
    }
  ],
  "frm_routing_algorithm": {
    "type": "single",
    "data": {
      "connector": "adyenplatform",
      "merchant_connector_id": "<string>"
    }
  },
  "organization_id": "org_q98uSGAYbjEwqs0mJwnz",
  "is_recon_enabled": true,
  "default_profile": "<string>",
  "recon_status": "not_requested",
  "pm_collect_link_config": {
    "logo": "https://hyperswitch.io/favicon.ico",
    "merchant_name": "Hyperswitch",
    "theme": "#4285F4",
    "domain_name": "<string>",
    "allowed_domains": [
      "<string>"
    ],
    "enabled_payment_methods": "[{\"payment_method\": \"bank_transfer\", \"payment_method_types\": [\"ach\", \"bacs\", \"sepa\"]}]"
  }
}

Get Started

Essentials

API Reference

Merchant Account - Create

Authorizations

Body

Response