> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rinne.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Update merchant

> Requires the merchant.company.edit permission.

Updates a specific merchant. The merchant must belong to the authenticated organization. Only specific fields can be updated via API for security reasons. Note that merchant status, document fields, and organization relationship cannot be modified through the API.




## OpenAPI

````yaml /api-spec.yaml patch /v1/merchants/{merchantId}
openapi: 3.1.0
info:
  title: Rinne API
  version: 1.0.0
  description: >
    **Rinne API** is a robust payment platform that offers integration with
    multiple payment providers.


    ## Authentication


    The API uses API Key authentication via the `x-api-key` header. Each company
    has a unique key to access resources.


    ## Response Format


    All responses follow a consistent format:

    - **Success**: Returns the requested data directly

    - **Error**: Returns an `error` object with detailed information


    ## Pagination


    Endpoints that return lists support pagination through parameters:

    - `page`: Page number (default: 1)

    - `limit`: Items per page (default: 20, maximum: 100)


    ## Supported Providers


    The API supports multiple payment providers:

    - **Rinne**: Internal provider

    - **Celcoin**: PIX integration and other financial services


    ## Raw Card Data (PCI Endpoints)


    Card credential fields (`card_data.number`, `card_data.cvv`,
    `card_data.network_token`,

    `card_data.cryptogram`, and the 3DS `card.number`) must always be sent
    encrypted —

    values start with the `ev:` prefix. Plaintext values are rejected with

    `400 VALIDATION_ERROR` on every host.


    There are two ways to send encrypted values:

    - **rinne-js**: card forms and wallet buttons (Apple Pay / Google Pay)
    encrypt
      credentials client-side before they leave the browser.
    - **PCI API host**: server-to-server integrations that handle raw card data
    must call
      `https://pci.api.rinne.com.br/core` (sandbox: `https://pci.api-sandbox.rinne.com.br/core`)
      instead of the regular host. This endpoint encrypts `number` and `cvv` in transit
      before the request reaches the API; all other fields pass through unchanged.

    The PCI host serves only transaction creation and 3DS session creation (both
    the

    self and merchant variants); use the regular host for everything else.
  contact:
    name: Rinne API Support
    email: suporte@rinne.com.br
servers:
  - url: https://api-sandbox.rinne.com.br/core
    description: Sandbox
  - url: https://api.rinne.com.br/core
    description: Production
security: []
tags:
  - name: System
    description: System and API health endpoints
  - name: Authentication
    description: User authentication and authorization endpoints
  - name: Management
    description: >-
      Merchant management endpoints - create, list, get specific, overview,
      update
  - name: Transactions
    description: Transaction operations for merchants - create, list, overview, refunds
  - name: Affiliations
    description: Affiliation management for merchants
  - name: Banking
    description: Banking operations for merchants - balance, cashout, statements
  - name: Bank Accounts
    description: Bank account management for merchants
  - name: Pix Keys
    description: PIX key management for merchants
  - name: Company Transactions
    description: Direct transaction management and query endpoints for companies
  - name: Companies
    description: Company management
  - name: Company Affiliations
    description: Payment provider affiliation management
  - name: Company Banking
    description: Company banking endpoints (balance, etc.)
  - name: Company Pix
    description: Company PIX key management
  - name: Company Ledger
    description: Company ledger entry query endpoints
  - name: Ledger
    description: Ledger entry query endpoints (company and merchants)
  - name: Webhooks
    description: Endpoints for receiving webhooks from external providers
  - name: Pricing
    description: Fee and cost policy management for transaction pricing
  - name: Users
    description: User management endpoints
  - name: Roles
    description: Role management endpoints
  - name: Permissions
    description: Permission management endpoints
  - name: Admin
    description: Admin management endpoints
    x-scalar-ignore: true
paths:
  /v1/merchants/{merchantId}:
    patch:
      tags:
        - Management
      summary: Update merchant
      description: >
        Requires the merchant.company.edit permission.


        Updates a specific merchant. The merchant must belong to the
        authenticated organization. Only specific fields can be updated via API
        for security reasons. Note that merchant status, document fields, and
        organization relationship cannot be modified through the API.
      parameters:
        - in: path
          name: merchantId
          required: true
          schema:
            type: string
          description: Merchant ID
          example: 123e4567-e89b-12d3-a456-426614174000
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCompanyInput'
            examples:
              partial_update:
                summary: Partial merchant update
                value:
                  name: Updated Merchant Name
                  contact:
                    email: new-email@merchant.com
                    phone: '+5511999999999'
                  transfer_configurations:
                    automatic_transfer_enabled: false
                    transfer_frequency: MONTHLY
                  metadata:
                    updated_reason: contact_information_change
                    last_modified_by: organization
      responses:
        '200':
          description: Merchant updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyResponse'
        '400':
          description: Validation error - Invalid field values or formats
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationErrorResponse'
        '403':
          description: Insufficient permissions to access this resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationErrorResponse'
        '404':
          description: Merchant not found or doesn't belong to organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    UpdateCompanyInput:
      type: object
      description: >-
        Schema for updating a company. Only specific fields can be updated for
        security reasons.
      properties:
        name:
          type: string
          description: Company display name
          example: Updated Company Name
        full_name:
          type: string
          description: Company full legal name
          example: Updated Company Full Legal Name
        document_tax_type:
          type: string
          enum:
            - PJ
            - MEI
            - ME
            - PF
          description: >
            Tax classification type. Can only be updated when the company has no
            affiliations in non-final statuses (only FAILED/REJECTED are
            allowed). Must be PF for CPF companies; PJ, MEI, or ME for CNPJ
            companies.
          example: MEI
        company_logo_url:
          type: string
          description: URL for company logo image
          example: https://example.com/new-logo.png
        contact:
          type: object
          description: Contact information (partial update supported)
          properties:
            first_name:
              type: string
              description: Contact person first name
              example: Jane
            last_name:
              type: string
              description: Contact person last name
              example: Smith
            phone:
              type: string
              description: Contact phone number (10-15 digits, + prefix optional)
              pattern: ^\+?[0-9]{10,15}$
              example: '+5511999999999'
            email:
              type: string
              format: email
              description: Contact email address
              example: jane@company.com
            mother_name:
              type: string
              description: Contact person's mother name
              example: Maria Smith
            birth_date:
              type: string
              pattern: ^[0-9]{2}-[0-9]{2}-[0-9]{4}$
              description: Birth date in DD-MM-YYYY format
              example: 20-05-1985
            document_number:
              type: string
              example: '81146431023'
              description: Contact's CPF number
            politically_exposed:
              type: boolean
              example: false
              description: Whether the contact person is politically exposed (PEP)
            declared_income:
              type: integer
              minimum: 0
              description: >-
                Monthly income in whole reais (BRL) for Banco Central compliance
                (Circular 3.978/2020)
              example: 5000
            occupation:
              type: string
              enum:
                - ADMINISTRATOR_MANAGER
                - SALES_REPRESENTATIVE
                - HR_ANALYST
                - FINANCIAL_ANALYST
                - SOFTWARE_DEVELOPER
                - MARKETING_PROFESSIONAL
                - HEALTHCARE_PROFESSIONAL
                - TEACHER
                - ENGINEER
                - LAWYER
                - GENERAL_SERVICES
                - CONSTRUCTION_WORKER
                - DRIVER
                - RECEPTIONIST
                - TECHNICIAN
                - DESIGNER
                - MACHINE_OPERATOR
                - CONSULTANT
                - BEAUTY_PROFESSIONAL
                - SECURITY_AGENT
                - AGRICULTURAL_WORKER
                - TRAVEL_AGENT
                - JOURNALIST
                - PSYCHOLOGIST
                - PUBLIC_SERVANT
                - RESEARCHER
                - ARTISAN
                - RETIRED
                - STUDENT
                - SELF_EMPLOYED
                - OTHER
              description: Contact person occupation for Banco Central compliance
              example: SOFTWARE_DEVELOPER
            net_worth:
              type: integer
              minimum: 0
              description: >-
                Total net worth in whole reais (BRL) for Banco Central
                compliance (Circular 3.978/2020)
              example: 50000
            address:
              type: object
              description: Contact address (partial update supported)
              properties:
                street:
                  type: string
                  description: Street name
                  example: New Contact Street
                street_number:
                  type: string
                  description: Street number
                  example: '789'
                complement:
                  type: string
                  description: Address complement
                  example: Apt 301
                neighborhood:
                  type: string
                  description: Neighborhood
                  example: New Contact Neighborhood
                zipcode:
                  type: string
                  description: ZIP code (5-9 digits)
                  pattern: ^[0-9]{5,9}$
                  example: '54321098'
                country:
                  type: string
                  description: Country code
                  example: '076'
                state:
                  type: string
                  description: State abbreviation
                  example: MG
                city:
                  type: string
                  description: City name
                  example: Belo Horizonte
        website_url:
          type: string
          description: Company website URL
          example: https://company.com
        address:
          type: object
          description: Company address (partial update supported)
          properties:
            street:
              type: string
              description: Street name
              example: New Street
            street_number:
              type: string
              description: Street number
              example: '456'
            complement:
              type: string
              description: Address complement
              example: Suite 201
            neighborhood:
              type: string
              description: Neighborhood
              example: New Neighborhood
            zipcode:
              type: string
              description: ZIP code (5-9 digits)
              pattern: ^[0-9]{5,9}$
              example: '87654321'
            country:
              type: string
              description: Country code
              example: '076'
            state:
              type: string
              description: State abbreviation
              example: SP
            city:
              type: string
              description: City name
              example: São Paulo
        transfer_configurations:
          type: object
          description: Transfer configurations (partial update supported)
          properties:
            automatic_transfer_enabled:
              type: boolean
              description: Enable automatic transfers
              example: false
            transfer_frequency:
              type: string
              enum:
                - DAILY
                - WEEKLY
                - MONTHLY
              description: Transfer frequency
              example: WEEKLY
            rail:
              type: string
              enum:
                - PIX
              description: Transfer rail
              example: PIX
            utc_hour_of_day:
              type: integer
              description: UTC hour of day for automatic transfers (0-23)
              minimum: 0
              maximum: 23
              example: 12
            day_of_week:
              type: integer
              description: Day of week for automatic transfers (1-7, where 1 is Sunday)
              minimum: 1
              maximum: 7
              example: 1
            day_of_month:
              type: integer
              description: Day of month for automatic transfers (1-31)
              minimum: 1
              maximum: 31
              example: 1
            min_balance:
              type: integer
              description: Minimum balance in cents for automatic transfers to trigger
              minimum: 1
              example: 1000
        declared_revenue:
          type: integer
          minimum: 0
          description: >-
            Annual revenue in whole reais (BRL) for Banco Central compliance
            (Circular 3.978/2020)
          example: 50000
        metadata:
          type: object
          description: Additional metadata as JSON object
          example:
            industry: technology
            tier: enterprise
    CompanyResponse:
      type: object
      description: Transformed company data returned by the API
      properties:
        id:
          type: string
          example: a3dbd0c2-9f79-4f86-8caa-47779b3f2793
        name:
          type: string
          example: Example Company
        full_name:
          type: string
          example: Example Company LTDA
        document_number:
          type: string
          example: '16525269000121'
        document_type:
          type: string
          enum:
            - CNPJ
            - CPF
          example: CNPJ
        document_tax_type:
          type: string
          enum:
            - PJ
            - MEI
            - ME
            - PF
          description: |
            Document tax type:
            - PF: Pessoa Física (Individual) - for CPF companies
            - PJ: Pessoa Jurídica (Legal Entity) - for CNPJ companies
            - MEI: Microempreendedor Individual - for CNPJ companies
            - ME: Microempresa (Micro Enterprise) - for CNPJ companies
          example: PJ
        company_logo_url:
          type: string
          example: https://example.com/logo.png
        contact:
          type: object
          properties:
            first_name:
              type: string
              example: John
            last_name:
              type: string
              example: Silva
            phone:
              type: string
              example: '+551199999999'
            email:
              type: string
              example: contact@example.com
            mother_name:
              type: string
              example: Maria Silva
            birth_date:
              type: string
              example: 15-08-1990
              description: Birth date in DD-MM-YYYY format
            document_number:
              type: string
              example: '81146431023'
              description: Contact's CPF number
            politically_exposed:
              type: boolean
              example: false
              description: Whether the contact person is politically exposed (PEP)
            declared_income:
              type: integer
              minimum: 0
              description: >-
                Monthly income in whole reais (BRL) for Banco Central compliance
                (Circular 3.978/2020)
              example: 5000
            occupation:
              type: string
              enum:
                - ADMINISTRATOR_MANAGER
                - SALES_REPRESENTATIVE
                - HR_ANALYST
                - FINANCIAL_ANALYST
                - SOFTWARE_DEVELOPER
                - MARKETING_PROFESSIONAL
                - HEALTHCARE_PROFESSIONAL
                - TEACHER
                - ENGINEER
                - LAWYER
                - GENERAL_SERVICES
                - CONSTRUCTION_WORKER
                - DRIVER
                - RECEPTIONIST
                - TECHNICIAN
                - DESIGNER
                - MACHINE_OPERATOR
                - CONSULTANT
                - BEAUTY_PROFESSIONAL
                - SECURITY_AGENT
                - AGRICULTURAL_WORKER
                - TRAVEL_AGENT
                - JOURNALIST
                - PSYCHOLOGIST
                - PUBLIC_SERVANT
                - RESEARCHER
                - ARTISAN
                - RETIRED
                - STUDENT
                - SELF_EMPLOYED
                - OTHER
              description: Contact person occupation for Banco Central compliance
              example: SOFTWARE_DEVELOPER
            net_worth:
              type: integer
              minimum: 0
              description: >-
                Total net worth in whole reais (BRL) for Banco Central
                compliance (Circular 3.978/2020)
              example: 50000
            address:
              type: object
              properties:
                street:
                  type: string
                  example: Contact Street
                street_number:
                  type: string
                  example: '456'
                complement:
                  type: string
                  example: Apt 201
                neighborhood:
                  type: string
                  example: Contact Neighborhood
                zipcode:
                  type: string
                  example: '87654321'
                country:
                  type: string
                  example: '076'
                state:
                  type: string
                  example: RJ
                city:
                  type: string
                  example: Rio de Janeiro
        status:
          type: string
          enum:
            - PENDING_ACTIVATION
            - ACTIVE
            - INACTIVE
            - BLOCKED
          example: ACTIVE
        website_url:
          type: string
          example: https://example.com
        address:
          type: object
          properties:
            street:
              type: string
              example: Example Street
            street_number:
              type: string
              example: '123'
            complement:
              type: string
              example: Suite 101
            neighborhood:
              type: string
              example: Downtown
            zipcode:
              type: string
              example: '12345678'
            country:
              type: string
              example: '076'
            state:
              type: string
              example: SP
            city:
              type: string
              example: São Paulo
        transfer_configurations:
          type: object
          properties:
            automatic_transfer_enabled:
              type: boolean
              example: true
            transfer_frequency:
              type: string
              enum:
                - DAILY
                - WEEKLY
                - MONTHLY
              example: DAILY
            rail:
              type: string
              enum:
                - PIX
              example: PIX
            utc_hour_of_day:
              type: integer
              example: 12
            day_of_week:
              type: integer
              example: 1
            day_of_month:
              type: integer
              example: 1
            min_balance:
              type: integer
              example: 1000
        webhook_enabled:
          type: boolean
          description: Whether webhooks are enabled for this company
          example: false
        declared_revenue:
          type:
            - integer
            - 'null'
          minimum: 0
          description: >-
            Annual revenue in whole reais (BRL) for Banco Central compliance
            (Circular 3.978/2020)
          example: 50000
        created_at:
          type: string
          format: date-time
          example: '2023-01-01T00:00:00Z'
        updated_at:
          type: string
          format: date-time
          example: '2023-01-01T00:00:00Z'
      required:
        - id
        - name
        - full_name
        - document_number
        - document_type
        - contact
        - status
        - api_key
        - address
        - transfer_configurations
        - created_at
        - updated_at
    ValidationErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: VALIDATION_ERROR
            message:
              type: string
              example: Validation error
            status:
              type: integer
              example: 400
            details:
              type: object
              properties:
                issues:
                  type: array
                  items:
                    type: object
                    properties:
                      field:
                        type: string
                        example: email
                      type:
                        type: string
                        example: REQUIRED
                      message:
                        type: string
                        example: Field 'email' is required
                      value:
                        anyOf:
                          - type: string
                          - type: number
                          - type: boolean
                        example: invalid_value
                      constraints:
                        type: object
                        example:
                          min: 18
                          max: 120
            path:
              type: string
              example: /companies
            timestamp:
              type: string
              format: date-time
              example: '2023-12-01T10:00:00.000Z'
            requestId:
              type: string
              example: req_123456789
    AuthenticationErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: AUTHENTICATION_ERROR
            message:
              type: string
              example: Authentication required to access this resource
            status:
              type: integer
              example: 401
            details:
              type: object
              properties:
                reason:
                  type: string
                  example: Invalid API key
            path:
              type: string
              example: /companies/me
            timestamp:
              type: string
              format: date-time
              example: '2023-12-01T10:00:00.000Z'
            requestId:
              type: string
              example: req_123456789
    AuthorizationErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: AUTHORIZATION_ERROR
            message:
              type: string
              example: You need 'admin' permissions to access this resource
            status:
              type: integer
              example: 403
            path:
              type: string
              example: /companies
            timestamp:
              type: string
              format: date-time
              example: '2023-12-01T10:00:00.000Z'
            requestId:
              type: string
              example: req_123456789
    NotFoundErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: RESOURCE_NOT_FOUND
            message:
              type: string
              example: Company with ID '123' not found
            status:
              type: integer
              example: 404
            path:
              type: string
              example: /companies/me
            timestamp:
              type: string
              format: date-time
              example: '2023-12-01T10:00:00.000Z'
            requestId:
              type: string
              example: req_123456789
    InternalServerErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: INTERNAL_SERVER_ERROR
            message:
              type: string
              example: An unexpected error occurred
            status:
              type: integer
              example: 500
            path:
              type: string
              example: /companies
            timestamp:
              type: string
              format: date-time
              example: '2023-12-01T10:00:00.000Z'
            requestId:
              type: string
              example: req_123456789
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Company API key for authentication

````