> ## Documentation Index > Fetch the complete documentation index at: https://docs.walletconnect.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a merchant > Create a new merchant under the authenticated partner. Requires an `Idempotency-Key` header so retries safely return the originally-created merchant rather than creating duplicates. ## OpenAPI ````yaml api/2026-02-18.json POST /v1/merchants openapi: 3.1.0 info: title: WalletConnect Pay API version: '2026-02-18' servers: - url: https://api.pay.walletconnect.com security: - API Key: [] - ApiKey: [] - AppId: [] tags: - name: Gateway - name: Payments - name: Refunds - name: Merchant Management - name: Settlements - name: Crypto Settlement paths: /v1/merchants: post: tags: - Merchant Management summary: Create a merchant description: >- Create a new merchant under the authenticated partner. Requires an `Idempotency-Key` header so retries safely return the originally-created merchant rather than creating duplicates. operationId: MerchantManagement_create parameters: - name: Idempotency-Key in: header required: true description: >- Unique key to ensure idempotent request processing. Max 255 characters. schema: type: string maxLength: 255 requestBody: required: true content: application/json: schema: type: object properties: merchantName: type: string minLength: 1 maxLength: 256 description: Display name for the merchant examples: - Acme Store merchantEmail: type: string format: email pattern: >- ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ description: Contact email for the merchant examples: - billing@acme.store iconUrl: default: null description: Merchant logo URL (HTTPS only), or null to unset examples: - https://example.com/logo.png anyOf: - type: string format: uri - type: 'null' required: - merchantName - merchantEmail examples: - merchantName: Acme Store merchantEmail: billing@acme.store iconUrl: https://example.com/logo.png responses: '201': description: Merchant created content: application/json: schema: type: object properties: merchant: type: object properties: id: type: string description: Merchant ID examples: - mrch_7kBz2qR9xPvLmN4Yw name: description: Merchant display name type: string email: anyOf: - type: string - type: 'null' description: Contact email examples: - billing@acme.store status: type: string enum: - active - inactive - suspended description: Current merchant status examples: - active createdAt: type: string description: ISO 8601 creation timestamp examples: - '2025-06-15T10:30:00.000Z' required: - id - name - email - status - createdAt required: - merchant example: merchant: id: mrch_7kBz2qR9xPvLmN4Yw name: Acme Store email: billing@acme.store status: active createdAt: '2025-06-15T10:30:00.000Z' '400': description: Bad request content: application/json: schema: type: object properties: message: type: string description: Human-readable error message code: type: string enum: - params_validation - missing_idempotency_key description: Machine-readable error code details: description: Additional structured error details type: object propertyNames: type: string additionalProperties: {} issues: type: array description: >- Field-level validation issues (present on validation errors) items: type: object required: - field - message properties: field: type: string message: type: string required: - message - code examples: params_validation: summary: Validation failed value: code: params_validation message: Validation failed missing_idempotency_key: summary: Missing Idempotency-Key header value: code: missing_idempotency_key message: Missing Idempotency-Key header '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string description: Human-readable error message code: type: string enum: - missing_api_key - invalid_api_key description: Machine-readable error code details: description: Additional structured error details type: object propertyNames: type: string additionalProperties: {} required: - message - code examples: missing_api_key: summary: Missing API key value: code: missing_api_key message: Missing API key invalid_api_key: summary: Invalid API key value: code: invalid_api_key message: Invalid API key '409': description: Idempotency conflict content: application/json: schema: type: object properties: message: type: string description: Human-readable error message code: type: string const: idempotency_conflict description: Machine-readable error code details: description: Additional structured error details type: object propertyNames: type: string additionalProperties: {} required: - message - code examples: idempotency_conflict: summary: >- Idempotency key conflict: same key was used with a different request body value: code: idempotency_conflict message: >- Idempotency key conflict: same key was used with a different request body '500': description: Internal error content: application/json: schema: type: object properties: message: type: string description: Human-readable error message code: type: string const: internal_error description: Machine-readable error code details: description: Additional structured error details type: object propertyNames: type: string additionalProperties: {} required: - message - code examples: internal_error: summary: Internal Server Error value: code: internal_error message: Internal Server Error '502': description: Bad gateway content: application/json: schema: type: object properties: message: type: string description: Human-readable error message code: type: string const: bad_gateway description: Machine-readable error code details: description: Additional structured error details type: object propertyNames: type: string additionalProperties: {} required: - message - code examples: bad_gateway: summary: Bad Gateway value: code: bad_gateway message: Bad Gateway components: securitySchemes: API Key: type: apiKey in: header name: Api-Key ApiKey: type: apiKey in: header name: Api-Key description: Private API key for wallet authentication AppId: type: apiKey in: header name: App-Id description: >- Public App ID for wallet authentication. When using this auth mode, the Client-Id header is also required. ````