Merchant Connector - Create

Create a Merchant Connector for a merchant account (payment processor, acquirer, fraud/accounting services, etc).

Example — cURL

Create a merchant account with custom connector label

cURL
curl --request POST \
  --url https://sandbox.hyperswitch.io/account/{account_id}/connectors \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '
{
  "test_mode": false,
  "disabled": false
}
'

Response (200):

Response (application/json)
{
  "connector_type": "payment_processor",
  "connector_name": "authipay",
  "merchant_connector_id": "mca_5apGeP94tMts6rg3U3kR",
  "profile_id": "<string>",
  "status": "inactive",
  "connector_label": "stripe_US_travel",
  "connector_account_details": {
    "connector_account_details": {},
    "metadata": {}
  },
  "payment_methods_enabled": [
    {
      "accepted_countries": {
        "list": [
          "FR",
          "DE",
          "IN"
        ],
        "type": "disable_only"
      },
      "accepted_currencies": {
        "list": [
          "USD",
          "EUR"
        ],
        "type": "enable_only"
      },
      "installment_payment_enabled": true,
      "maximum_amount": 68607706,
      "minimum_amount": 1,
      "payment_method": "wallet",
      "payment_method_issuers": [
        "labore magna ipsum",
        "aute"
      ],
      "payment_method_types": [
        "upi_collect",
        "upi_intent"
      ],
      "payment_schemes": [
        "Discover",
        "Discover"
      ],
      "recurring_enabled": true
    }
  ],
  "connector_webhook_details": {
    "merchant_secret": "12345678900987654321",
    "additional_secret": "12345678900987654321"
  },
  "metadata": {},
  "test_mode": false,
  "disabled": false,
  "frm_configs": "\n[{\"gateway\":\"stripe\",\"payment_methods\":[{\"payment_method\":\"card\",\"payment_method_types\":[{\"payment_method_type\":\"credit\",\"card_networks\":[\"Visa\"],\"flow\":\"pre\",\"action\":\"cancel_txn\"},{\"payment_method_type\":\"debit\",\"card_networks\":[\"Visa\"],\"flow\":\"pre\"}]}]}]\n",
  "business_country": "AF",
  "business_label": "travel",
  "business_sub_label": "chase",
  "applepay_verified_domains": [
    "<string>"
  ],
  "pm_auth_config": {},
  "additional_merchant_data": {
    "open_banking_recipient_data": {
      "connector_recipient_id": "<string>"
    }
  },
  "connector_wallets_details": {
    "apple_pay_combined": {},
    "apple_pay": {},
    "amazon_pay": {},
    "samsung_pay": {},
    "paze": {},
    "google_pay": {}
  }
}

HTTP Request

POST /account/{account_id}/connectors

Authorizations

  • api-key (string, header, 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

Body (application/json)

Create a new Merchant Connector for the merchant account.

Fields:

  • connector_type (enum, required) Type of the Connector for the financial use case. Could range from Payments to Accounting to Banking. Available options: payment_processor, payment_vas, fin_operations, fiz_operations, networks, banking_entities, non_banking_finance, payout_processor, payment_method_auth, authentication_processor, tax_processor, billing_processor, vault_processor

  • connector_name (enum, required) Available options (partial list shown; full list available in response schema): See expandable block below for the full list.

connector_name — Full list of available options

authipay, adyenplatform, stripe_billing_test, phonypay, fauxpay, pretendpay, stripe_test, adyen_test, checkout_test, paypal_test, aci, adyen, affirm, airwallex, amazonpay, archipel, authorizedotnet, bambora, bamboraapac, bankofamerica, barclaycard, billwerk, bitpay, bluesnap, blackhawknetwork, calida, boku, braintree, breadpay, cardinal, cashtocode, celero, chargebee, checkbook, checkout, coinbase, coingate, custombilling, cryptopay, ctp_mastercard, ctp_visa, cybersource, datatrans, deutschebank, digitalvirgo, dlocal, dwolla, ebanx, elavon, facilitapay, finix, fiserv, fiservemea, fiuu, flexiti, forte, getnet, gigadat, globalpay, globepay, gocardless, gpayments, hipay, helcim, hyperswitch_vault, inespay, iatapay, itaubank, jpmorgan, juspaythreedsserver, klarna, loonio, mifinity, mollie, moneris, multisafepay, netcetera, nexinets, nexixpay, nmi, nomupay, noon, nordea, novalnet, nuvei, opennode, paybox, payload, payme, payone, paypal, paysafe, paystack, paytm, payu, peachpayments, payjustnow, payjustnowinstore, phonepe, placetopay, powertranz, prophetpay, rapyd, razorpay, recurly, redsys, santander, shift4, silverflow, square, stax, stripe, stripebilling, taxjar, threedsecureio, tesouro, tokenex, tokenio, trustpay, trustpayments, tsys, vgs, volt, wellsfargo, wise, worldline, worldpay, worldpayvantiv, worldpayxml, worldpaymodular, signifyd, plaid, riskified, xendit, zen, zift, zsl

  • connector_label (string | null) Unique label to identify this connector account on the Hyperswitch dashboard and reports. Example: "stripe_US_travel"

  • profile_id (string | null) Identifier for the profile; if not provided default will be chosen from merchant account. Maximum string length: 64

  • connector_account_details (object) Connector-specific account details

  • payment_methods_enabled (object[] | null) An array of objects detailing payment methods to enable under this merchant connector account. Example:

  • connector_webhook_details (object) Webhook secrets and details for the connector

  • metadata (object) Metadata for storing additional unstructured information on the object

  • test_mode (boolean | null, default: false) Indicates if the connector is in Test mode. Example: false

  • disabled (boolean | null, default: false) Indicates if the connector is disabled. Example: false

  • frm_configs (object[] | null) Contains the FRM configs for the merchant connector. Example stringified config: "\n[{\"gateway\":\"stripe\",\"payment_methods\":[{\"payment_method\":\"card\",\"payment_method_types\":[{\"payment_method_type\":\"credit\",\"card_networks\":[\"Visa\"],\"flow\":\"pre\",\"action\":\"cancel_txn\"},{\"payment_method_type\":\"debit\",\"card_networks\":[\"Visa\"],\"flow\":\"pre\"}]}]}]\n"

  • business_country (enum) Two-letter country code. Full list is large; see expandable block below.

business_country — Full list of country codes

AF, AX, AL, DZ, AS, AD, AO, AI, AQ, AG, AR, AM, AW, AU, AT, AZ, BS, BH, BD, BB, BY, BE, BZ, BJ, BM, BT, BO, BQ, BA, BW, BV, BR, IO, BN, BG, BF, BI, KH, CM, CA, CV, KY, CF, TD, CL, CN, CX, CC, CO, KM, CG, CD, CK, CR, CI, HR, CU, CW, CY, CZ, DK, DJ, DM, DO, EC, EG, SV, GQ, ER, EE, ET, FK, FO, FJ, FI, FR, GF, PF, TF, GA, GM, GE, DE, GH, GI, GR, GL, GD, GP, GU, GT, GG, GN, GW, GY, HT, HM, VA, HN, HK, HU, IS, IN, ID, IR, IQ, IE, IM, IL, IT, JM, JP, JE, JO, KZ, KE, KI, KP, KR, KW, KG, LA, LV, LB, LS, LR, LY, LI, LT, LU, MO, MK, MG, MW, MY, MV, ML, MT, MH, MQ, MR, MU, YT, MX, FM, MD, MC, MN, ME, MS, MA, MZ, MM, NA, NR, NP, NL, NC, NZ, NI, NE, NG, NU, NF, MP, NO, OM, PK, PW, PS, PA, PG, PY, PE, PH, PN, PL, PT, PR, QA, RE, RO, RU, RW, BL, SH, KN, LC, MF, PM, VC, WS, SM, ST, SA, SN, RS, SC, SL, SG, SX, SK, SI, SB, SO, ZA, GS, SS, ES, LK, SD, SR, SJ, SZ, SE, CH, SY, TW, TJ, TZ, TH, TL, TG, TK, TO, TT, TN, TR, TM, TC, TV, UG, UA, AE, GB, UM, UY, UZ, VU, VE, VN, VG, VI, WF, EH, YE, ZM, ZW, US

  • business_label (string | null) Business label the connector account is attached to. To be deprecated; use profile_id instead.

  • business_sub_label (string | null) Business sublabel the connector account is attached to. To be deprecated; use profile_id instead. Example: "chase"

  • merchant_connector_id (string | null) Unique ID of the connector. Example: "mca_5apGeP94tMts6rg3U3kR"

  • pm_auth_config (object) Payment method auth configuration

  • status (enum) inactive or active

  • additional_merchant_data (object) Additional merchant-specific data (e.g., open banking recipient data)

  • connector_wallets_details (object) Details for wallet integrations (apple_pay, google_pay, etc.)

Response (200 — application/json)

Merchant Connector Created — returns the created merchant connector object. Fields largely mirror the request body plus:

  • connector_type (enum, required)

  • connector_name (enum, required)

  • merchant_connector_id (string, required) — Unique ID of the merchant connector account. Example: "mca_5apGeP94tMts6rg3U3kR"

  • profile_id (string, required) — Identifier for the profile (max length 64)

  • status (enum, required) — inactive or active

  • connector_label (string | null) — Example: "stripe_US_travel"

  • connector_account_details (object)

  • payment_methods_enabled (object[] | null)

  • connector_webhook_details (object)

  • metadata (object)

  • test_mode (boolean | null, default: false)

  • disabled (boolean | null, default: false)

  • frm_configs (object[] | null)

  • business_country (enum)

  • business_label (string | null) — Example: "travel"

  • business_sub_label (string | null) — Example: "chase"

  • applepay_verified_domains (string[] | null)

  • pm_auth_config (object)

  • additional_merchant_data (object)

  • connector_wallets_details (object)

Example response body is shown in the Example section above.

Was this page helpful?

  • Yes / No

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

Related:

  • API Key - List: https://api-reference.hyperswitch.io/v1/api-key/api-key--list

  • Merchant Connector - Retrieve: https://api-reference.hyperswitch.io/v1/merchant-connector-account/merchant-connector--retrieve

Responses are generated using AI and may contain mistakes.

Previousmerchant-connector-accountNextpayment-methods