Profile - Create

Create a business profile for a merchant account.

POST https://sandbox.hyperswitch.io/account/{account_id}/business_profile

Request example (cURL)

curl --request POST \
  --url https://sandbox.hyperswitch.io/account/{account_id}/business_profile \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '
{
  "enable_payment_response_hash": true,
  "redirect_to_merchant_with_http_post": false,
  "payment_link_config": {
    "display_sdk_only": false,
    "enabled_saved_payment_method": false,
    "hide_card_nickname_field": false,
    "show_card_form_by_default": true,
    "business_specific_configs": {
      "display_sdk_only": false,
      "enabled_saved_payment_method": false,
      "hide_card_nickname_field": false,
      "show_card_form_by_default": true
    }
  },
  "collect_shipping_details_from_wallet_connector": false,
  "collect_billing_details_from_wallet_connector": false,
  "always_collect_shipping_details_from_wallet_connector": false,
  "always_collect_billing_details_from_wallet_connector": false,
  "payout_link_config": {
    "payout_test_mode": false
  }
}
'

Successful response (200)

{
  "merchant_id": "y3oqhf46pyzuxjbcn2giaqnb44",
  "profile_id": "pro_abcdefghijklmnopqrstuvwxyz",
  "profile_name": "<string>",
  "enable_payment_response_hash": true,
  "redirect_to_merchant_with_http_post": true,
  "is_tax_connector_enabled": true,
  "is_network_tokenization_enabled": false,
  "is_auto_retries_enabled": false,
  "is_click_to_pay_enabled": false,
  "is_clear_pan_retries_enabled": true,
  "force_3ds_challenge": true,
  "is_pre_network_tokenization_enabled": false,
  "return_url": "https://www.example.com/success",
  "payment_response_hash_key": "<string>",
  "webhook_details": {
    "payment_statuses_enabled": [
      "succeeded",
      "failed",
      "partially_captured",
      "requires_merchant_action"
    ],
    "refund_statuses_enabled": [
      "success",
      "failure"
    ],
    "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_statuses_enabled": [
      "success",
      "failed"
    ]
  },
  "metadata": {},
  "routing_algorithm": {},
  "intent_fulfillment_time": 900,
  "frm_routing_algorithm": {},
  "payout_routing_algorithm": {
    "type": "single",
    "data": {
      "connector": "authipay",
      "merchant_connector_id": "<string>"
    }
  },
  "applepay_verified_domains": ["<string>"],
  "session_expiry": 900,
  "payment_link_config": {
    "theme": "#4E6ADD",
    "logo": "https://i.pinimg.com/736x/4d/83/5c/4d835ca8aafbbb15f84d07d926fda473.jpg",
    "seller_name": "hyperswitch",
    "sdk_layout": "accordion",
    "display_sdk_only": true,
    "enabled_saved_payment_method": true,
    "hide_card_nickname_field": true,
    "show_card_form_by_default": true,
    "transaction_details": [
      {
        "key": "Policy-Number",
        "value": "297472368473924",
        "ui_configuration": {
          "position": 5,
          "is_key_bold": true,
          "is_value_bold": true
        }
      }
    ],
    "background_image": {
      "url": "https://hyperswitch.io/favicon.ico",
      "position": "left",
      "size": {
        "Variants": "cover"
      }
    },
    "details_layout": "layout1",
    "payment_button_text": "<string>",
    "custom_message_for_card_terms": "<string>",
    "custom_message_for_payment_method_types": [
      {
        "payment_method": "card",
        "payment_method_types": [
          {
            "message": {
              "display_mode": "custom",
              "value": "Sample message"
            },
            "payment_method_type": "credit"
          }
        ]
      }
    ],
    "payment_button_colour": "<string>",
    "skip_status_screen": true,
    "payment_button_text_colour": "<string>",
    "background_colour": "<string>",
    "sdk_ui_rules": {},
    "payment_link_ui_rules": {},
    "enable_button_only_on_form_ready": true,
    "payment_form_header_text": "<string>",
    "payment_form_label_type": "above",
    "show_card_terms": "always",
    "is_setup_mandate_flow": true,
    "color_icon_card_cvc_error": "<string>",
    "domain_name": "<string>",
    "business_specific_configs": {},
    "allowed_domains": ["<string>"],
    "branding_visibility": true
  },
  "authentication_connector_details": {
    "authentication_connectors": ["threedsecureio"],
    "three_ds_requestor_url": "<string>",
    "three_ds_requestor_app_url": "<string>"
  },
  "use_billing_as_payment_method_billing": true,
  "extended_card_info_config": {
    "public_key": "<string>",
    "ttl_in_secs": 900
  },
  "collect_shipping_details_from_wallet_connector": false,
  "collect_billing_details_from_wallet_connector": false,
  "always_collect_shipping_details_from_wallet_connector": false,
  "always_collect_billing_details_from_wallet_connector": false,
  "is_connector_agnostic_mit_enabled": true,
  "payout_link_config": {
    "allowed_domains": ["<string>"],
    "logo": "https://hyperswitch.io/favicon.ico",
    "merchant_name": "Hyperswitch",
    "theme": "#4285F4",
    "domain_name": "<string>",
    "form_layout": "tabs",
    "payout_test_mode": false
  },
  "outgoing_webhook_custom_http_headers": {},
  "tax_connector_id": "<string>",
  "max_auto_retries_enabled": 123,
  "always_request_extended_authorization": true,
  "authentication_product_ids": {},
  "card_testing_guard_config": {
    "card_ip_blocking_status": "enabled",
    "card_ip_blocking_threshold": 123,
    "guest_user_card_blocking_status": "enabled",
    "guest_user_card_blocking_threshold": 123,
    "customer_id_blocking_status": "enabled",
    "customer_id_blocking_threshold": 123,
    "card_testing_guard_expiry": 123
  },
  "is_debit_routing_enabled": true,
  "merchant_business_country": "AF",
  "acquirer_configs": [
    {
      "profile_acquirer_id": "pro_acq_LCRdERuylQvNQ4qh3QE0",
      "acquirer_assigned_merchant_id": "M123456789",
      "merchant_name": "NewAge Retailer",
      "network": "VISA",
      "acquirer_bin": "456789",
      "acquirer_fraud_rate": 0.01,
      "profile_id": "pro_ky0yNyOXXlA5hF8JzE5q",
      "acquirer_ica": "401288"
    }
  ],
  "is_iframe_redirection_enabled": false,
  "merchant_category_code": "5411",
  "merchant_country_code": "<string>",
  "dispute_polling_interval": 2,
  "is_manual_retry_enabled": true,
  "always_enable_overcapture": true,
  "is_external_vault_enabled": "enable",
  "external_vault_connector_details": {
    "vault_connector_id": "<string>",
    "vault_sdk": "vgs_sdk",
    "vault_token_selector": [
      {
        "token_type": "card_number"
      }
    ]
  },
  "billing_processor_id": "<string>",
  "is_l2_l3_enabled": true
}

Authorizations

• Header: api-key (string, required)

Use the API key created under your merchant account from the HyperSwitch dashboard. API key is used to authenticate API requests from your merchant server only. Don't expose this key on a website or embed it in a mobile application.

Path parameters

• account_id (string, required) — The unique identifier for the merchant account.

Request body (application/json)

Top-level properties (all shown types reflect what's accepted; many are optional):

• profile_name: string | null The name of profile. Maximum length: 64.

• return_url: string | null URL to redirect after completion. Example: "https://www.example.com/success". Maximum length: 255.

• enable_payment_response_hash: boolean | null (default: true) If payment response hash needs to be enabled.

• payment_response_hash_key: string | null Hash key used for calculating the signature for webhooks and redirect response. If not provided, a value is autogenerated.

• redirect_to_merchant_with_http_post: boolean | null (default: false) If redirect to merchant with HTTP POST needs to be enabled.

• webhook_details: object Configure webhook behaviours (see response example for structure).

• metadata: object Additional unstructured information stored on the profile.

• routing_algorithm: object Routing algorithm for payments.

• intent_fulfillment_time: integer (>= 0) | null Time (seconds) till which a payment is active after session starts. Example: 900.

• frm_routing_algorithm: object Routing algorithm for FRM.

• payout_routing_algorithm: object Payout routing configuration (see response example for structure).

• applepay_verified_domains: string[] | null Verified Apple Pay domains for the profile.

• session_expiry: integer (>= 0) | null Client secret default expiry for all payments on this profile. Example: 900.

• payment_link_config: object UI and behavior config for payment links (see response example for full structure).

• authentication_connector_details: object Authentication connector related configuration.

• use_billing_as_payment_method_billing: boolean | null Whether to use billing details passed when creating the intent as payment-method billing.

• collect_shipping_details_from_wallet_connector: boolean | null (default: false) Collect shipping details from wallet connector only if required by connector.

• collect_billing_details_from_wallet_connector: boolean | null (default: false) Collect billing details from wallet connector only if required by connector.

• always_collect_shipping_details_from_wallet_connector: boolean | null (default: false) Always collect shipping details from wallet connector.

• always_collect_billing_details_from_wallet_connector: boolean | null (default: false) Always collect billing details from wallet connector.

• is_connector_agnostic_mit_enabled: boolean | null If MIT (merchant-initiated transactions) can be processed via a different connector than CIT.

• payout_link_config: object GenericLinkUiConfig for payout links (see response example).

• outgoing_webhook_custom_http_headers: object Custom headers to be included in outgoing webhooks. Recommended not to use more than four key-value pairs.

• tax_connector_id: string | null Merchant Connector id for tax_calculator connector.

• is_tax_connector_enabled: boolean Indicates whether tax_calculator connector is enabled. If true, tax_connector_id is considered.

• is_network_tokenization_enabled: boolean Indicates if network tokenization is enabled.

• is_auto_retries_enabled: boolean | null Indicates if auto retries are enabled.

• max_auto_retries_enabled: integer (>= 0) | null Maximum number of auto retries allowed for a payment.

• always_request_extended_authorization: boolean | null If extended authentication must be requested for all payments.

• is_click_to_pay_enabled: boolean Indicates if click to pay is enabled.

• authentication_product_ids: object Product authentication ids.

• card_testing_guard_config: object Anti-fraud/test guard configuration (see response example).

• is_clear_pan_retries_enabled: boolean | null Indicates if clear PAN retries is enabled.

• force_3ds_challenge: boolean | null Whether 3DS challenge is forced.

• is_debit_routing_enabled: boolean | null Indicates if debit routing is enabled.

• merchant_business_country: enum (string) Merchant business country. Available options include ISO country codes such as AF, IN, US, etc. (see full list in response description).

• is_iframe_redirection_enabled: boolean | null Whether redirection should open inside an iframe.

• is_pre_network_tokenization_enabled: boolean | null Indicates if pre-network tokenization is enabled.

• merchant_category_code: string Example: "5411".

• merchant_country_code: string Wrapper type for merchant country codes.

• dispute_polling_interval: integer (hours) | null Interval in hours for polling connector to check for new disputes. Example: 2.

• is_manual_retry_enabled: boolean | null If manual retry for payment is enabled.

• always_enable_overcapture: boolean | null If overcapture must be requested for all payments.

• is_external_vault_enabled: enum ("enable" | "skip") Whether an external vault is enabled or skipped.

• external_vault_connector_details: object Details for external vault (vault_connector_id, vault_sdk, vault_token_selector, etc.).

• billing_processor_id: string | null Merchant Connector id to be stored for billing_processor connector.

• is_l2_l3_enabled: boolean | null Enable Level 2 / Level 3 processing data for card transactions.

(Refer to the request example and the response example for nested object structures and additional fields like payment_link_config, webhook_details, authentication_connector_details, card_testing_guard_config, acquirer_configs, external_vault_connector_details, etc.)

Response fields (application/json)

On success (200) returns the created profile object. Key fields include:

• merchant_id (string) — Identifier for Merchant Account.

• profile_id (string) — Identifier for the profile. Use this to create merchant accounts, payments, and payouts.

• profile_name (string) — Profile name.

• enable_payment_response_hash (boolean) — Whether payment response hash is enabled.

• redirect_to_merchant_with_http_post (boolean) — Whether redirect with HTTP POST is enabled.

• is_tax_connector_enabled (boolean)

• is_network_tokenization_enabled (boolean)

• is_auto_retries_enabled (boolean)

• is_click_to_pay_enabled (boolean)

• is_clear_pan_retries_enabled (boolean)

• force_3ds_challenge (boolean)

• is_pre_network_tokenization_enabled (boolean)

• return_url (string | null)

• payment_response_hash_key (string | null)

• webhook_details (object) — Webhook configuration and enabled statuses.

• metadata (object)

• routing_algorithm (object)

• intent_fulfillment_time (integer)

• frm_routing_algorithm (object)

• payout_routing_algorithm (object)

• applepay_verified_domains (string[])

• session_expiry (integer)

• payment_link_config (object)

• authentication_connector_details (object)

• use_billing_as_payment_method_billing (boolean)

• extended_card_info_config (object)

• collect_shipping_details_from_wallet_connector (boolean)

• collect_billing_details_from_wallet_connector (boolean)

• always_collect_shipping_details_from_wallet_connector (boolean)

• always_collect_billing_details_from_wallet_connector (boolean)

• is_connector_agnostic_mit_enabled (boolean)

• payout_link_config (object)

• outgoing_webhook_custom_http_headers (object)

• tax_connector_id (string | null)

• max_auto_retries_enabled (integer | null)

• always_request_extended_authorization (boolean | null)

• authentication_product_ids (object)

• card_testing_guard_config (object)

• is_debit_routing_enabled (boolean)

• merchant_business_country (string) — ISO country code.

• acquirer_configs (object[]) — Array of acquirer configuration objects.

• is_iframe_redirection_enabled (boolean | null)

• merchant_category_code (string)

• merchant_country_code (string)

• dispute_polling_interval (integer | null)

• is_manual_retry_enabled (boolean | null)

• always_enable_overcapture (boolean | null)

• is_external_vault_enabled (string: "enable" | "skip")

• external_vault_connector_details (object)

• billing_processor_id (string | null)

• is_l2_l3_enabled (boolean | null)

Refer to the response example for full nested structures and sample values.

Notes and examples

• payment_response_hash_key: If not provided, one is autogenerated.

• webhook_details: You can enable/disable specific webhook events and provide webhook credentials and URL.

• Many boolean fields default to false unless specified; check the request example and response example to confirm defaults.

Links

• Documentation: https://api-reference.hyperswitch.io/introduction

• Locker API Reference: https://api-reference.hyperswitch.io/locker-api-reference/overview

• Intelligent Router API Reference: https://api-reference.hyperswitch.io/intelligent-router-api-reference/overview

• Edit docs (GitHub): https://github.com/juspay/hyperswitch/edit/main/api-reference/v1/business-profile/business-profile--create.mdx

• Raise issue (GitHub): https://github.com/juspay/hyperswitch/issues/new?title=Issue%20on%20docs&body=Path:%20/v1/business-profile/business-profile--create

If you want, I can convert nested objects (payment_link_config, webhook_details, payout_routing_algorithm, card_testing_guard_config, acquirer_configs, external_vault_connector_details) into detailed sub-sections for easier editing in GitBook.