> ## Documentation Index > Fetch the complete documentation index at: https://developer.hellgate.io/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml /products/commerce/v2/openapi.yaml post /merchants openapi: 3.1.0 info: title: Commerce API version: '2.0' description: > The Commerce V2 API provides a comprehensive payment orchestration platform designed to streamline and optimize payment processing for modern businesses. Built with flexibility and security at its core, our API enables you to process payments, manage authentications, and handle cardholder data across multiple payment processors without vendor lock-in. contact: name: Starfish GmbH & Co. KG email: hello@starfish.team url: https://hellgate.io/cpa/commerce license: name: Commerce API Terms url: https://hellgate.io/terms-and-conditions servers: - url: https://sandbox.hellgate.io description: Commerce SaaS Sandbox - url: https://api.hellgate.io description: Commerce SaaS Production security: [] tags: - name: payments_ci description: >- Handle payment processing where the customer is actively present and authorizing the transaction. - name: payments_mi description: >- Process transactions without direct customer interaction at the time of payment. - name: payments_modifications description: >- Modify existing payment transactions after initial authorization (capture, void, refund). - name: payments_data description: >- Access comprehensive payment transaction data for reporting, reconciliation, and analysis. - name: refunds_data description: Access detailed refund transaction data for tracking and reconciliation. - name: authentications_ci description: >- Process EMVCo 3-D Secure authentication requests as standalone transactions (one-off, recurring, installment). - name: authentications_mi description: >- Process requestor-initiated EMVCo 3-D Secure authentication requests (3RI) as standalone transactions. - name: authentications_data description: Access the results of prior authentications for reference. - name: credentials_management description: >- Manage stored payment credentials for repeat customers across all operating models. - name: tokens_create description: >- Create and import Commerce tokens to securely store cardholder data while maintaining PCI DSS compliance. - name: tokens_management description: Manage stored Commerce tokens including CVC2 security code management. - name: compliance_service description: >- Safely handle sensitive cardholder data while maintaining PCI DSS compliance via a secure proxy service. - name: network_tokens description: >- Manage network tokens with major card schemes with automatic lifecycle management. - name: merchants description: >- Configure and manage merchant accounts based on your chosen operating model. - name: reconciliation description: Reconcile imported token data. - name: processor_backup description: >- Migrate payment tokens from third-party processors (currently supports stripe.com). paths: /merchants: post: tags: - merchants summary: Create a merchant description: | 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. operationId: onboard_merchant requestBody: content: application/json: schema: $ref: '#/components/schemas/MerchantOnboarding' responses: '200': description: Success response content: application/json: schema: $ref: '#/components/schemas/MerchantFirstTime' '401': $ref: '#/components/responses/401_UnauthorizedError' '403': $ref: '#/components/responses/403_ForbiddenError' '422': $ref: '#/components/responses/422_ValidationError' security: - APIKeyAuth: [] components: schemas: MerchantOnboarding: type: object properties: company_city: type: string description: The city in the merchant's primary address. country_code: $ref: '#/components/schemas/ISO3166-2-CountryCode' legal_name: type: string description: The name of the merchant website_url: type: string description: The URL of the merchant's website format: uri identity_and_verification_enabled: type: boolean description: > The flag indicates if the 3DS identity and verification is required or not (only allowed for primary) 3ds_enabled: type: boolean description: | Indicates if 3DS is available or not for the Merchant default_currency: $ref: '#/components/schemas/CurrencyCode' default_merchant_id: type: string description: The id for the Merchant schemes: type: array description: > The schemes supported by the merchant (required if merchant has a merchant_id) items: $ref: '#/components/schemas/MerchantScheme' example: company_city: Berlin country_code: DE legal_name: Example Merchant website_url: https://example.com identity_and_verification_enabled: false 3ds_enabled: true default_currency: EUR default_merchant_id: '1234567890' schemes: - name: visa acquirer_bin: '40001' requestor_id: 123456789.visa requestor_name: 3dsclient.local.visa category_code: '3200' merchant_id: '' merchant_name: '' required: - company_city - country_code - legal_name - website_url MerchantFirstTime: type: object properties: id: type: string description: The ID of the merchant format: uuid created_at: type: string description: The date-time the merchant was created (following ISO 8601) format: date-time company_city: type: string description: The city in the merchant's primary address. country_code: $ref: '#/components/schemas/ISO3166-2-CountryCode' encryption_key: type: string description: > 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. legal_name: type: string description: The name of the merchant website_url: type: string description: The URL of the merchant's website format: uri example: id: 00000000-0000-0000-0000-000000000000 created_at: '2023-10-10T00:00:00Z' company_city: Berlin country_code: DE encryption_key: eyJhbGciOiJSUzI1NiIsImVudGl0bGVtZW50IjoiYWF4NXdq... legal_name: Example Merchant website_url: https://example.com required: - id - created_at - company_city - country_code - encryption_key - legal_name - website_url ISO3166-2-CountryCode: type: string description: | A two letter country code. [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) CurrencyCode: type: string description: | The three letter currency code. See: [ISO-4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) MerchantScheme: type: object properties: name: type: string description: The network scheme name enum: - visa - mastercard acquirer_bin: type: string description: The acquiring institution identification code requestor_id: type: string description: | The 3DS requestor identifier requestor_id and requestor_name should be sent in pairs. requestor_name: type: string description: | The 3DS requestor name requestor_id and requestor_name should be sent in pairs. category_code: type: string description: The DS-specific code describing the Merchant type of business format: '0000' merchant_id: type: string description: > 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. merchant_name: type: string description: > 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. required: - name - acquirer_bin - category_code ErrorGeneric: type: object properties: code: $ref: '#/components/schemas/ErrorStatusCode' classifier: $ref: '#/components/schemas/ErrorClassifier' message: $ref: '#/components/schemas/ErrorMessage' ErrorValidation: type: object properties: code: $ref: '#/components/schemas/ErrorStatusCode' classifier: $ref: '#/components/schemas/ErrorClassifier' message: $ref: '#/components/schemas/ErrorMessage' validation_errors: type: array items: type: object properties: path: type: string description: Json-path in the request which points to the validation error message: type: string description: Human readable validation message ErrorStatusCode: type: integer description: The corresponding HTTP status code for the error ErrorClassifier: type: string description: Technical code that helps to identify the error ErrorMessage: type: string description: Human readable representation of the error responses: 401_UnauthorizedError: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorGeneric' example: code: 401 message: No valid means of authentication was provided classifier: UNAUTHORIZED 403_ForbiddenError: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorGeneric' example: code: 403 message: Not allowed to access this resource or feature classifier: FORBIDDEN 422_ValidationError: description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorValidation' example: code: 422 classifier: VALIDATION_ERROR message: Validation error validation_errors: - path: json-path message: human readable error message securitySchemes: APIKeyAuth: type: apiKey name: X-API-Key in: header ````