Profile - Create

POST /v2/profiles

Create a profile.

Request example (cURL)

Create profile (curl)
curl --request POST \
  --url https://sandbox.hyperswitch.io/v2/profiles \
  --header 'Content-Type: application/json' \
  --header 'X-Merchant-Id: <x-merchant-id>' \
  --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_if_required": false,
  "collect_billing_details_from_wallet_connector_if_required": false,
  "always_collect_shipping_details_from_wallet_connector": false,
  "always_collect_billing_details_from_wallet_connector": false,
  "payout_link_config": {
    "payout_test_mode": false
  },
  "is_click_to_pay_enabled": false,
  "split_txns_enabled": "skip"
}
'

Successful response (200)

Authorization

  • Header: api-key (string, required) Admin API keys allow privileged actions such as creating merchant and connector accounts.

Required headers

  • X-Merchant-Id (string, required) — Merchant ID of the profile.

Body parameters (application/json)

  • profile_name (string, required) The name of profile. Maximum length: 64.

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

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

  • payment_response_hash_key (string | null) Hash key used to calculate signatures for webhooks and redirect responses. If omitted, a value is generated.

  • redirect_to_merchant_with_http_post (boolean | null) — default: false If true, redirect to merchant with HTTP POST. Example: true

  • webhook_details (object) Webhook configuration (see response for fields shown in example).

  • metadata (object) Freeform metadata for the profile.

  • order_fulfillment_time (integer) Time (in seconds) till which a payment is active after session starts. Required range: x >= 0. Example: 900

  • order_fulfillment_time_origin (enum) Options: create, confirm

  • applepay_verified_domains (string[]) Verified Apple Pay domains for this profile.

  • session_expiry (integer) Client secret default expiry for payments under this profile. Required range: x >= 0. Example: 900

  • payment_link_config (object) Payment link / UI config (see examples in request/response).

  • authentication_connector_details (object) Authentication connectors and related fields.

  • 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_if_required (boolean | null) — default: false Collect shipping details from wallet connector only if required by the connector (e.g., Apple Pay).

  • collect_billing_details_from_wallet_connector_if_required (boolean | null) — default: false

  • always_collect_shipping_details_from_wallet_connector (boolean | null) — default: false

  • always_collect_billing_details_from_wallet_connector (boolean | null) — default: false

  • is_connector_agnostic_mit_enabled (boolean | null) If true, MITs (merchant initiated transactions) may be processed through a different connector than CITs based on routing rules. If false, MIT uses the same connector as CIT.

  • payout_link_config (object) Generic link UI config for payouts.

  • outgoing_webhook_custom_http_headers (object) Additional custom headers sent in outgoing webhook requests (recommended: <= 4 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 will be checked.

  • is_network_tokenization_enabled (boolean) Indicates if network tokenization is enabled.

  • is_click_to_pay_enabled (boolean) — default: false

  • authentication_product_ids (object) Product authentication ids.

  • card_testing_guard_config (object) Card testing guard configuration (see example fields).

  • is_clear_pan_retries_enabled (boolean | null)

  • is_debit_routing_enabled (boolean | null)

  • merchant_business_country (enum) ISO country code for merchant business country (examples: AF, IN, US, etc.)

  • is_iframe_redirection_enabled (boolean | null) Indicates if redirection should open inside an iframe.

  • is_external_vault_enabled (boolean | null)

  • external_vault_connector_details (object) External vault configuration (see example).

  • merchant_category_code (string) e.g. "5411"

  • merchant_country_code (string)

  • split_txns_enabled (enum) — default: skip Options: enable, skip

  • billing_processor_id (string | null)

  • is_l2_l3_enabled (boolean | null) Flag to enable Level 2 and Level 3 processing data for card transactions.

Response fields (200 — Account Created)

Key response fields shown in example:

  • merchant_id (string) — identifier for Merchant Account.

  • id (string) — profile identifier (use when creating merchant accounts, payments, payouts).

  • profile_name (string)

  • enable_payment_response_hash (boolean)

  • redirect_to_merchant_with_http_post (boolean)

  • is_tax_connector_enabled (boolean)

  • is_network_tokenization_enabled (boolean)

  • is_click_to_pay_enabled (boolean)

  • is_clear_pan_retries_enabled (boolean)

  • split_txns_enabled (enum)

  • return_url (string | null)

  • payment_response_hash_key (string | null)

  • webhook_details (object)

  • metadata (object)

  • applepay_verified_domains (string[])

  • session_expiry (integer)

  • payment_link_config (object)

  • authentication_connector_details (object)

  • use_billing_as_payment_method_billing (boolean | null)

  • extended_card_info_config (object)

  • collect_from_wallet_connector (booleans)

  • is_connector_agnostic_mit_enabled (boolean | null)

  • payout_link_config (object)

  • outgoing_webhook_custom_http_headers (object)

  • order_fulfillment_time (integer)

  • order_fulfillment_time_origin (enum)

  • tax_connector_id (string | null)

  • should_collect_cvv_during_payment (boolean | null)

  • authentication_product_ids (object)

  • card_testing_guard_config (object)

  • is_debit_routing_enabled (boolean | null)

  • merchant_business_country (enum)

  • is_iframe_redirection_enabled (boolean | null)

  • is_external_vault_enabled (boolean | null)

  • external_vault_connector_details (object)

  • merchant_category_code (string)

  • merchant_country_code (string)

  • revenue_recovery_retry_algorithm_type (enum: monitoring, smart, cascading)

  • billing_processor_id (string | null)

  • is_l2_l3_enabled (boolean | null)

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

Links in this page:

  • API reference root: https://api-reference.hyperswitch.io/

  • 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

  • Related pages:

    • Merchant Account - Profile List: https://api-reference.hyperswitch.io/v2/merchant-account/business-profile--list

    • Profile - Update: https://api-reference.hyperswitch.io/v2/profile/profile--update

PreviousProfile - Retrieve Default Fallback Routing AlgorithmNextMerchant Account - Retrieve