> ## 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 new merchant

> Requires the merchant.company.create permission.

Creates a new merchant company under the authenticated organization. The organization_id is automatically set from the authenticated organization.




## OpenAPI

````yaml /api-spec.yaml post /v1/merchants
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:
    post:
      tags:
        - Management
      summary: Create new merchant
      description: >
        Requires the merchant.company.create permission.


        Creates a new merchant company under the authenticated organization. The
        organization_id is automatically set from the authenticated
        organization.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCompanyInput'
            example:
              full_name: Merchant Store Ltda.
              name: Merchant Store
              document_number: '16525269000121'
              document_type: CNPJ
              document_tax_type: PJ
              mcc: '5912'
              contact:
                first_name: Store
                last_name: Manager
                phone: '+551188888888'
                email: manager@merchantstore.com
                mother_name: Manager Mother
                birth_date: 20-05-1985
                document_number: '81146431023'
                politically_exposed: false
                declared_income: 5000
                occupation: SOFTWARE_DEVELOPER
                net_worth: 50000
                role: PARTNER
                address:
                  street: Merchant Street
                  street_number: '789'
                  neighborhood: Business District
                  zipcode: '11223344'
                  country: '076'
                  state: SP
                  city: São Paulo
              address:
                street: Store Address
                street_number: '456'
                neighborhood: Commercial Area
                zipcode: '55667788'
                country: '076'
                state: RJ
                city: Rio de Janeiro
              transfer_configurations:
                automatic_transfer_enabled: true
                transfer_frequency: WEEKLY
                rail: PIX
                utc_hour_of_day: 12
                day_of_week: 1
                day_of_month: 1
                min_balance: 1000
              declared_revenue: 50000
              website_url: https://merchantstore.com
              bank_account:
                branch_number: '1234'
                account_number: '123456'
                account_type: CHECKING
                account_holder_name: Merchant Store Ltda.
                account_holder_document_number: '16525269000121'
                ispb: '00000000'
      responses:
        '201':
          description: Merchant created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyResponse'
        '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'
        '403':
          description: Insufficient permissions to access this resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationErrorResponse'
        '409':
          description: Conflict - Merchant with this document already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    CreateCompanyInput:
      type: object
      description: Schema for creating a new company or merchant
      required:
        - full_name
        - document_number
        - document_type
        - document_tax_type
        - mcc
        - contact
        - address
        - transfer_configurations
      properties:
        name:
          type: string
          description: Company short name (optional)
          example: Example Co
        full_name:
          type: string
          description: Company full name (required)
          example: Example Company Ltda.
        document_number:
          type: string
          description: >-
            Company document number (CPF: 11 digits; CNPJ: 14 characters,
            numeric or alphanumeric per IN RFB 2229/2024)
          example: '16525269000121'
        document_type:
          type: string
          enum:
            - CPF
            - CNPJ
          description: Document type (case insensitive, will be converted to uppercase)
          example: CNPJ
        document_tax_type:
          type: string
          enum:
            - PJ
            - MEI
            - ME
            - PF
          description: |
            Document tax type (required for all companies):
            - PF: Pessoa Física (Individual) - **for CPF companies only**
            - PJ: Pessoa Jurídica (Legal Entity) - for CNPJ companies
            - MEI: Microempreendedor Individual - for CNPJ companies
            - ME: Microempresa (Micro Enterprise) - for CNPJ companies

            **Validation Rules:**
            - For CPF companies: must be 'PF'
            - For CNPJ companies: must be one of 'PJ', 'MEI', or 'ME'
          example: PJ
        mcc:
          type: string
          description: Merchant Category Code (required)
          pattern: ^[0-9]{4}$
          example: '5912'
        contact:
          type: object
          required:
            - first_name
            - last_name
            - phone
            - email
            - mother_name
            - birth_date
            - document_number
            - address
          properties:
            first_name:
              type: string
              description: Contact person first name
              example: John
            last_name:
              type: string
              description: Contact person last name
              example: Silva
            phone:
              type: string
              pattern: ^\\+?[0-9]{10,15}$
              description: Contact phone number with country code
              example: '+551199999999'
            email:
              type: string
              format: email
              description: Contact email address
              example: contact@example.com
            mother_name:
              type: string
              description: Contact person mother name
              example: Maria Silva
            birth_date:
              type: string
              pattern: ^[0-9]{2}-[0-9]{2}-[0-9]{4}$
              example: 15-08-1990
              description: Contact birth date in DD-MM-YYYY format
            document_number:
              type: string
              description: >-
                Contact's CPF number (11 digits only). Must match company
                document for CPF companies
              pattern: ^[0-9]{11}$
              example: '81146431023'
            politically_exposed:
              type: boolean
              description: Whether the contact person is politically exposed (PEP)
              default: false
              example: false
            declared_income:
              type: integer
              minimum: 0
              description: >
                Monthly income in whole reais (BRL) for Banco Central compliance
                (Circular 3.978/2020).

                Optional - defaults to 5000 (R$ 5.000) if not provided.
              default: 5000
              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.
                Optional - defaults to 'OTHER' if not provided.
              default: OTHER
              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).

                Optional - defaults to 50000 (R$ 50.000) if not provided.
              default: 50000
              example: 50000
            role:
              type: string
              enum:
                - PARTNER
                - REPRESENTATIVE
              description: >
                Contact role - PARTNER (partner/shareholder) or REPRESENTATIVE
                (legal representative acting via power of attorney).

                Optional - defaults to PARTNER if not provided.
              default: PARTNER
              example: PARTNER
            address:
              type: object
              required:
                - street
                - neighborhood
                - zipcode
                - country
                - state
                - city
              properties:
                street:
                  type: string
                  description: Contact street address
                  example: Contact Street
                street_number:
                  type: string
                  description: Contact street number (optional)
                  example: '456'
                complement:
                  type: string
                  description: Contact address complement (optional)
                  example: Apt 201
                neighborhood:
                  type: string
                  description: Contact neighborhood
                  example: Contact Neighborhood
                zipcode:
                  type: string
                  description: Contact ZIP code (8 digits)
                  pattern: ^[0-9]{8}$
                  example: '87654321'
                country:
                  type: string
                  description: Contact country code
                  example: '076'
                state:
                  type: string
                  description: Contact state code (2 letters)
                  example: RJ
                city:
                  type: string
                  description: Contact city name
                  example: Rio de Janeiro
        address:
          type: object
          required:
            - street
            - neighborhood
            - zipcode
            - country
            - state
            - city
          properties:
            street:
              type: string
              description: Company street address
              example: Example Street
            street_number:
              type: string
              description: Company street number (optional)
              example: '123'
            complement:
              type: string
              description: Company address complement (optional)
              example: Suite 101
            neighborhood:
              type: string
              description: Company neighborhood
              example: Downtown
            zipcode:
              type: string
              description: Company ZIP code (8 digits)
              pattern: ^[0-9]{8}$
              example: '12345678'
            country:
              type: string
              description: Company country code
              example: '076'
            state:
              type: string
              description: Company state code (2 letters)
              example: SP
            city:
              type: string
              description: Company city name
              example: São Paulo
        company_logo_url:
          type: string
          format: uri
          description: Company logo URL (optional)
          example: https://example.com/logo.png
        website_url:
          type: string
          format: uri
          description: Company website URL (optional)
          example: https://example.com
        transfer_configurations:
          type: object
          required:
            - automatic_transfer_enabled
            - transfer_frequency
            - rail
          properties:
            automatic_transfer_enabled:
              type: boolean
              description: Enable automatic transfers
              default: true
              example: true
            transfer_frequency:
              type: string
              enum:
                - DAILY
                - WEEKLY
                - MONTHLY
              description: >-
                Transfer frequency (case insensitive, will be converted to
                uppercase)
              default: DAILY
              example: WEEKLY
            rail:
              type: string
              enum:
                - PIX
              description: Transfer rail (case insensitive, will be converted to uppercase)
              default: PIX
              example: PIX
            utc_hour_of_day:
              type: integer
              description: >-
                UTC hour of day for automatic transfers (0-23). Applied to all
                frequency types.
              minimum: 0
              maximum: 23
              example: 12
              default: 12
            day_of_week:
              type: integer
              description: >-
                Day of week for automatic transfers (1-7, where 1 is Sunday).
                Applied only to WEEKLY frequency type.
              minimum: 1
              maximum: 7
              example: 1
              default: 2
            day_of_month:
              type: integer
              description: >-
                Day of month for automatic transfers (1-31). Applied only to
                MONTHLY frequency type.
              minimum: 1
              maximum: 31
              example: 1
              default: 1
            min_balance:
              type: integer
              description: >-
                Minimum balance in cents for automatic transfers to trigger.
                Applied to all frequency types.
              minimum: 1
              example: 1000
              default: 1
        fee_policy_id:
          type: string
          description: >-
            Fee policy ID (optional), will be inherited from organization for
            merchants
          example: 123e4567-e89b-12d3-a456-426614174001
        metadata:
          type: object
          description: Additional metadata (optional JSON object)
          additionalProperties: true
          example:
            custom_field: value
        declared_revenue:
          type:
            - integer
            - 'null'
          minimum: 0
          description: >
            Annual revenue in whole reais (BRL) for Banco Central compliance
            (Circular 3.978/2020).

            Optional - defaults to 50000 (R$ 50.000) for CNPJ companies if not
            provided.
          default: 50000
          example: 50000
        bank_account:
          allOf:
            - $ref: '#/components/schemas/CreateCompanyBankAccountRequest'
          description: >-
            Bank account information, if sent a bank account will be created for
            the company
        gateway_affiliation:
          allOf:
            - $ref: '#/components/schemas/AffiliationRegisterRequest'
          description: >
            Optional. When provided, a gateway-mode affiliation is registered
            for the new

            merchant in the same request. Requires a gateway-mode cost policy to
            already

            exist for the organization. See Gateway Mode.
    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
          description: >-
            CPF (11 digits) or CNPJ (14 characters). CNPJ may be numeric or
            alphanumeric (IN RFB 2229/2024): first 12 positions are [A-Z0-9],
            last 2 are numeric check digits. Formatting is stripped and letters
            are uppercased on input.
          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
            role:
              type: string
              enum:
                - PARTNER
                - REPRESENTATIVE
              description: >-
                Contact role - PARTNER (partner/shareholder) or REPRESENTATIVE
                (legal representative acting via power of attorney)
              example: PARTNER
            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
    ConflictErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: CONFLICT_ERROR
            message:
              type: string
              example: A bank account with this account_number and ispb already exists
            status:
              type: integer
              example: 409
            details:
              type: object
              properties:
                field:
                  type: string
                  example: account_number
                value:
                  type: string
                  example: '12345678'
            path:
              type: string
              example: /companies/bank-accounts
            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
    CreateCompanyBankAccountRequest:
      type: object
      description: Schema for creating a new company bank account
      required:
        - branch_number
        - account_number
        - account_type
        - account_holder_name
        - account_holder_document_number
        - ispb
      properties:
        nickname:
          type: string
          minLength: 1
          maxLength: 100
          description: >-
            Optional user-defined label to distinguish accounts (e.g. when
            holding multiple accounts at the same bank)
          example: Main operations account
        branch_number:
          type: string
          pattern: ^\d+$
          description: Branch number (digits only)
          example: '0001'
        account_number:
          type: string
          pattern: ^\d+$
          description: Account number (digits only)
          example: '12345678'
        account_type:
          type: string
          enum:
            - CHECKING
            - SAVINGS
            - SALARY
            - PAYMENT
          description: Account type
          example: CHECKING
        account_holder_name:
          type: string
          description: Account holder full name
          example: John Doe Silva
        account_holder_document_number:
          type: string
          description: Account holder document number (CPF or CNPJ)
          example: '12345678901'
        ispb:
          type: string
          description: ISPB (Brazilian Payment System Identifier)
          example: '12345678'
    AffiliationRegisterRequest:
      type: object
      description: |
        Schema for registering a gateway-mode affiliation. Unlike create, no
        settlement bank account or anticipation config is accepted; the
        affiliation is persisted directly as ACTIVE.
      required:
        - provider
        - allowed_capture_methods
        - allowed_payment_methods
      properties:
        provider:
          type: string
          enum:
            - CAPPTA
          description: Payment provider name. Only CAPPTA supports Gateway Mode.
          example: CAPPTA
        allowed_capture_methods:
          type: array
          items:
            type: string
            enum:
              - ECOMMERCE
          description: >-
            Allowed capture methods. Gateway Mode covers online
            (card-not-present) capture only.
          example:
            - ECOMMERCE
          minItems: 1
        allowed_payment_methods:
          type: array
          items:
            type: string
            enum:
              - CREDIT_CARD
              - DEBIT_CARD
          description: Allowed payment methods. CAPPTA supports card payments only.
          example:
            - CREDIT_CARD
            - DEBIT_CARD
          minItems: 1
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Company API key for authentication

````