Connector Account - Create

Create a new Merchant Connector for the merchant account. The connector could be a payment processor / facilitator / acquirer or specialized services like Fraud / Accounting etc.

POST /v2/connector-accounts

Try it

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

Response (200 — Merchant Connector Created)

application/json
{
  "connector_type": "payment_processor",
  "connector_name": "authipay",
  "id": "mca_5apGeP94tMts6rg3U3kR",
  "profile_id": "<string>",
  "payment_methods_enabled": [
    {
      "payment_method_type": "card",
      "payment_method_subtypes": [
        {
          "payment_method_type": "ach",
          "payment_experience": "redirect_to_url",
          "card_networks": [
            "Visa"
          ],
          "accepted_currencies": {
            "type": "enable_only",
            "list": [
              "AED"
            ]
          },
          "accepted_countries": {
            "type": "enable_only",
            "list": [
              "AF"
            ]
          },
          "minimum_amount": 123,
          "maximum_amount": 123,
          "recurring_enabled": false,
          "installment_payment_enabled": true
        }
      ]
    }
  ],
  "status": "inactive",
  "connector_label": "stripe_US_travel",
  "connector_account_details": {
    "connector_account_details": {},
    "metadata": {}
  },
  "connector_webhook_details": {
    "merchant_secret": "12345678900987654321",
    "additional_secret": "12345678900987654321"
  },
  "metadata": {},
  "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",
  "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": {}
  },
  "feature_metadata": {
    "revenue_recovery": {
      "max_retry_count": "15",
      "billing_connector_retry_threshold": "10",
      "billing_account_reference": "{ \"mca_vDSg5z6AxnisHq5dbJ6g\": \"stripe_123\", \"mca_vDSg5z6AumisHqh4x5m1\": \"adyen_123\" }"
    }
  }
}

Authorizations

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

Request 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.

    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 — all options supported by the API are valid): 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

  • profile_id (string, required) Identifier for the profile. If not provided, default will be chosen from merchant account. Maximum length: 64.

  • payment_methods_enabled (object, required) Details of all the payment methods enabled for the connector for the given merchant account. (Contains child attributes.)

  • connector_label (string | null) An optional unique label to identify this connector account in the Hyperswitch dashboard and reports. If not provided, defaults to connector_name_profile_name. Example: "stripe_US_travel"

  • connector_account_details (object) (Show child attributes.)

  • connector_webhook_details (object) (Show child attributes.)

  • metadata (object) Metadata is useful for storing additional, unstructured information on an object.

  • 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: "\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"

  • pm_auth_config (object) pm_auth_config will relate MCA records to their respective chosen auth services, based on payment_method and pmt.

  • status (enum) Available options: inactive, active

  • additional_merchant_data (object) (Show child attributes.)

  • connector_wallets_details (object) (Show child attributes.)

  • feature_metadata (object) Feature metadata for merchant connector account (show child attributes).

Response (200 — application/json)

Merchant Connector Created.

Fields

  • connector_type (enum, required) Same available options as request.

  • connector_name (enum, required) Same available options as request.

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

  • profile_id (string, required) Identifier for the profile. Maximum length: 64.

  • payment_methods_enabled (object[]) (required) An object containing details about the payment methods enabled under this merchant connector account. (Contains child attributes.)

  • status (enum, required) inactive or active

  • connector_label (string | null) Unique label to identify the connector account. Example: "stripe_US_travel"

  • connector_account_details (object) (Show child attributes.)

  • connector_webhook_details (object) (Show child attributes.)

  • metadata (object) Metadata is useful for storing additional, unstructured information on an object.

  • disabled (boolean | null) — default: false

  • frm_configs (object[] | null) Contains the frm configs for the merchant connector.

  • applepay_verified_domains (string[] | null) Identifiers for verified domains of a particular connector account.

  • pm_auth_config (object) pm_auth_config will relate MCA records to their respective chosen auth services, based on payment_method and pmt.

  • additional_merchant_data (object) (Show child attributes.)

  • connector_wallets_details (object) (Show child attributes.)

  • feature_metadata (object) Feature metadata for merchant connector account (show child attributes).

If you need the full detailed schema for specific child attributes (e.g., payment_methods_enabled, connector_account_details, connector_wallets_details, feature_metadata), let me know which one and I will expand that section.

PreviousSubscription - Cancel SubscriptionNextOutgoing webhook