# Create a merchant

Create a new merchant.

Merchants represent legal entities which are interacting with the card
networks.

Onboarding merchants for an account is a prerequisite for creating
network tokens. Depending on the setup of the account, this allows to 
render complex ecommerce ecosystem setups.

Endpoint: POST /merchants
Version: 2.0
Security: APIKeyAuth

## Request fields (application/json):

  - `company_city` (string, required)
    The city in the merchant's primary address.
    Example: "Berlin"

  - `country_code` (string, required)
    A two letter country code.
[ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)

  - `legal_name` (string, required)
    The name of the merchant
    Example: "Example Merchant"

  - `website_url` (string, required)
    The URL of the merchant's website
    Example: "https://example.com"

  - `identity_and_verification_enabled` (boolean)
    The flag indicates if the 3DS identity and verification is required or not (only allowed for primary)

  - `3ds_enabled` (boolean)
    Indicates if 3DS is available or not for the Merchant
    Example: true

  - `default_currency` (string)
    The three letter currency code.
See: [ISO-4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes)

  - `default_merchant_id` (string)
    The id for the Merchant
    Example: "1234567890"

  - `schemes` (array)
    The schemes supported by the merchant (required if merchant has a merchant_id)
    Example: [{"name":"visa","acquirer_bin":"40001","requestor_id":"123456789.visa","requestor_name":"3dsclient.local.visa","category_code":"3200","merchant_id":"","merchant_name":""}]

  - `schemes.name` (string, required)
    The network scheme name
    Enum: "visa", "mastercard"

  - `schemes.acquirer_bin` (string, required)
    The acquiring institution identification code

  - `schemes.requestor_id` (string)
    The 3DS requestor identifier
requestor_id and requestor_name should be sent in pairs.

  - `schemes.requestor_name` (string)
    The 3DS requestor name
requestor_id and requestor_name should be sent in pairs.

  - `schemes.category_code` (string, required)
    The DS-specific code describing the Merchant type of business

  - `schemes.merchant_id` (string)
    Allow override the acquiring merchant id that can be used to specify per card scheme during
the authentication.
merchant_id and merchant_name should be sent in pairs.

  - `schemes.merchant_name` (string)
    Allow override the merchant name that can be used to specify per card scheme during the
authentication.
merchant_id and merchant_name should be sent in pairs.

## Response 200 fields (application/json):

  - `id` (string, required)
    The ID of the merchant
    Example: "00000000-0000-0000-0000-000000000000"

  - `created_at` (string, required)
    The date-time the merchant was created (following ISO 8601)
    Example: "2023-10-10T00:00:00Z"

  - `company_city` (string, required)
    The city in the merchant's primary address.
    Example: "Berlin"

  - `country_code` (string, required)
    A two letter country code.
[ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)

  - `encryption_key` (string, required)
    The key used to encrypt authentication data (for instance network token and cryptogram).
This information is returned only once, when the merchant was initially created. Subsequent calls will return a masked value.
    Example: "eyJhbGciOiJSUzI1NiIsImVudGl0bGVtZW50IjoiYWF4NXdq..."

  - `legal_name` (string, required)
    The name of the merchant
    Example: "Example Merchant"

  - `website_url` (string, required)
    The URL of the merchant's website
    Example: "https://example.com"

## Response 401 fields (application/json):

  - `code` (integer)
    The corresponding HTTP status code for the error

  - `classifier` (string)
    Technical code that helps to identify the error

  - `message` (string)
    Human readable representation of the error

## Response 403 fields (application/json):

  - `code` (integer)
    The corresponding HTTP status code for the error

  - `classifier` (string)
    Technical code that helps to identify the error

  - `message` (string)
    Human readable representation of the error

## Response 422 fields (application/json):

  - `code` (integer)
    The corresponding HTTP status code for the error

  - `classifier` (string)
    Technical code that helps to identify the error

  - `message` (string)
    Human readable representation of the error

  - `validation_errors` (array)

  - `validation_errors.path` (string)
    Json-path in the request which points to the validation error

  - `validation_errors.message` (string)
    Human readable validation message