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

# Create a PIX key for a merchant

> Requires the merchant.banking.create permission.

Registers a new PIX key for a merchant that belongs to the authenticated organization
company. A DICT lookup is always performed against the merchant's active 
affiliation before creating the key, and the result is returned in
`dict_key_information`. Per BACEN's rules, several fields may be masked
(e.g. account number, account type, owner document) as part of DICT's read-attack
prevention; values should be passed through as returned when initiating payments.

The request fails with 404 if the merchant is not found, does not belong to the
authenticated organization, or does not have an active valid affiliation with a
bank account.




## OpenAPI

````yaml /api-spec.yaml post /v1/merchants/{merchantId}/pix-keys
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: Cards
    description: Stored card management (self and merchant)
  - 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
paths:
  /v1/merchants/{merchantId}/pix-keys:
    post:
      tags:
        - Bank Accounts
      summary: Create a PIX key for a merchant
      description: >
        Requires the merchant.banking.create permission.


        Registers a new PIX key for a merchant that belongs to the authenticated
        organization

        company. A DICT lookup is always performed against the merchant's
        active 

        affiliation before creating the key, and the result is returned in

        `dict_key_information`. Per BACEN's rules, several fields may be masked

        (e.g. account number, account type, owner document) as part of DICT's
        read-attack

        prevention; values should be passed through as returned when initiating
        payments.


        The request fails with 404 if the merchant is not found, does not belong
        to the

        authenticated organization, or does not have an active valid affiliation
        with a

        bank account.
      parameters:
        - in: path
          name: merchantId
          required: true
          schema:
            type: string
          description: The merchant ID
          example: 123e4567-e89b-12d3-a456-426614174000
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCompanyPixKeyRequest'
      responses:
        '201':
          description: |
            PIX key created successfully. The response always includes
            `dict_key_information` (object from DICT when available, or `null`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyPixKeyResponse'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationErrorResponse'
        '404':
          description: >
            Merchant not found or does not belong to authenticated organization
            company,

            or the merchant has no active affiliation with a bank account.
          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:
    CreateCompanyPixKeyRequest:
      type: object
      description: Schema for creating a new company PIX key
      required:
        - key
      properties:
        key:
          type: string
          description: PIX key value
          example: merchant@example.com
        primary:
          type: boolean
          description: Whether this is the primary PIX key
          example: false
    CompanyPixKeyResponse:
      type: object
      description: Company PIX key response
      required:
        - id
        - company_id
        - key_type
        - key
        - primary
        - status
        - deleted_at
        - created_at
        - updated_at
        - dict_key_information
      properties:
        id:
          type: string
          format: uuid
          description: PIX key ID
          example: 123e4567-e89b-12d3-a456-426614174001
        company_id:
          type: string
          format: uuid
          description: Company ID
          example: a3dbd0c2-9f79-4f86-8caa-47779b3f2793
        key_type:
          type: string
          enum:
            - CPF
            - CNPJ
            - EMAIL
            - PHONE
            - EVP
          description: PIX key type
          example: EMAIL
        key:
          type: string
          description: PIX key value
          example: merchant@example.com
        primary:
          type: boolean
          description: Whether this is the primary PIX key
          example: false
        status:
          type: string
          enum:
            - ACTIVE
            - DELETED
          description: PIX key status
          example: ACTIVE
        deleted_at:
          type:
            - string
            - 'null'
          format: date-time
          description: Deletion timestamp (null if not deleted)
          example: null
        created_at:
          type: string
          format: date-time
          description: Creation timestamp
          example: '2025-01-01T10:00:00.000Z'
        updated_at:
          type: string
          format: date-time
          description: Last update timestamp
          example: '2025-01-01T10:05:00.000Z'
        dict_key_information:
          type:
            - object
            - 'null'
          description: >
            Last persisted DICT key lookup snapshot for this PIX key (from
            create or

            update). Always present on every company and merchant PIX key
            response; use

            `null` when no snapshot is stored (for example legacy keys) or the
            stored

            snapshot is invalid.


            Per BACEN's rules, DICT applies masking to protect against read
            attacks;

            fields such as account number, account type, and owner document may
            appear

            partially or fully masked (e.g. asterisks). Use the values as
            returned for any

            follow-up payment initiation on the same flow.
          properties:
            bank:
              type: string
              description: Recipient PSP ISPB (participant)
              example: '18236120'
            account:
              type: string
              description: Recipient account number as returned by DICT (may be masked)
              example: '********'
            branch:
              type: string
              description: Recipient branch number
              example: '0'
            account_type:
              type: string
              description: Recipient account type as returned by DICT (may be masked)
              example: '********'
            owner_name:
              type: string
              description: Legal name or full name of the key owner as returned by DICT
              example: teste celcoin
            owner_document:
              type: string
              description: >-
                CPF or CNPJ as returned by DICT (often masked for natural
                persons)
              example: '***778477**'
            is_owned_by_company:
              type: boolean
              description: >
                True when the DICT key is owned by the same legal entity
                (CPF/CNPJ)

                as the company registering the key. Corresponds to Celcoin's

                `isSameTaxId` field, which is only populated when `ownerTaxId`
                is

                sent in the lookup (which this endpoint always does).
              example: true
          required:
            - bank
            - account
            - branch
            - account_type
            - owner_name
            - owner_document
            - is_owned_by_company
    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
    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

````