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

# List affiliations

> Gets a list of affiliations for the authenticated company with optional filters and pagination.
Requires the affiliation.list permission.




## OpenAPI

````yaml /api-spec.yaml get /v1/affiliations
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/affiliations:
    get:
      tags:
        - Company Affiliations
      summary: List affiliations
      description: >
        Gets a list of affiliations for the authenticated company with optional
        filters and pagination.

        Requires the affiliation.list permission.
      parameters:
        - in: query
          name: provider
          schema:
            type: string
            enum:
              - CELCOIN
              - RINNE
              - CAPPTA
          description: >-
            Filter by provider (accepts lowercase and uppercase, returns
            uppercase)
          example: CELCOIN
        - in: query
          name: status
          schema:
            type: string
            enum:
              - PENDING
              - ACTIVE
              - PROCESSING
              - BLOCKED
              - PENDING_APPROVAL
              - WAITING_DOCUMENTS
              - PROCESSING_DOCUMENTS
              - REJECTED
              - FAILED
              - INVALID_SETTLEMENT_BANK_ACCOUNT
          description: Filter by status
          example: ACTIVE
        - in: query
          name: enabled
          schema:
            type: boolean
          description: Filter by enabled status
          example: true
        - in: query
          name: merchant_id
          schema:
            type: string
          description: Filter by merchant ID
          example: '12345678'
        - name: page
          in: query
          description: Page number
          schema:
            type: integer
            minimum: 1
            default: 1
          example: 1
        - name: limit
          in: query
          description: Number of items per page
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
          example: 20
        - in: query
          name: sort
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
              enum:
                - created_at
                - updated_at
                - '-created_at'
                - '-updated_at'
          description: >-
            Multi-field sort string (e.g., -created_at). Allowed fields:
            created_at, updated_at
          example: '-created_at'
      responses:
        '200':
          description: List of affiliations
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AffiliationResponse'
                  pagination:
                    $ref: '#/components/schemas/PaginationResponse'
        '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'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    AffiliationResponse:
      type: object
      description: Transformed affiliation data returned by the API
      properties:
        id:
          type: string
          example: 123e4567-e89b-12d3-a456-426614174002
        provider:
          type: string
          enum:
            - CELCOIN
            - RINNE
            - CAPPTA
          description: Payment provider name
          example: CELCOIN
        provider_id:
          type:
            - string
            - 'null'
          description: ID in provider system
          example: prov_123456
        soft_descriptor:
          type:
            - string
            - 'null'
          description: Soft descriptor for transactions
          example: MYSTORE
        merchant_id:
          type: string
          description: Merchant ID in provider
          example: '12345678'
        mcc:
          type: string
          description: Merchant Category Code
          example: '5411'
        cost_policy_id:
          type:
            - string
            - 'null'
          description: Associated cost policy ID
          example: 123e4567-e89b-12d3-a456-426614174003
        status:
          type: string
          enum:
            - PENDING
            - ACTIVE
            - PROCESSING
            - BLOCKED
            - PENDING_APPROVAL
            - WAITING_DOCUMENTS
            - PROCESSING_DOCUMENTS
            - REJECTED
            - FAILED
            - INVALID_SETTLEMENT_BANK_ACCOUNT
          description: Current affiliation status
          example: ACTIVE
        provider_status_code:
          type:
            - string
            - 'null'
          description: Provider-specific status code
          example: '200'
        provider_status_message:
          type:
            - string
            - 'null'
          description: Provider-specific status message
          example: Merchant activated successfully
        provider_metadata:
          type:
            - object
            - 'null'
          nullable: true
          description: Provider-specific metadata
          example: {}
        enabled:
          type: boolean
          description: Whether the affiliation is enabled
          example: true
        company_id:
          type: string
          description: Associated company ID
          example: a3dbd0c2-9f79-4f86-8caa-47779b3f2793
        onboarding_url:
          type:
            - string
            - 'null'
          description: Onboarding URL (only shown when status is not ACTIVE)
          example: https://provider.com/onboard/12345
        bank_account:
          anyOf:
            - allOf:
                - $ref: '#/components/schemas/BankAccount'
            - type: 'null'
          description: Associated bank account information (created by provider)
        settlement_bank_accounts:
          type: array
          items:
            $ref: '#/components/schemas/SettlementBankAccountResponse'
          description: Settlement bank accounts for this affiliation.
        allowed_capture_methods:
          type: array
          items:
            type: string
            enum:
              - EMV
              - MAGSTRIPE
              - ECOMMERCE
              - CONTACTLESS_ICC
          description: Allowed capture methods
          example:
            - ECOMMERCE
        allowed_payment_methods:
          type: array
          items:
            type: string
            enum:
              - CREDIT_CARD
              - DEBIT_CARD
              - PIX
              - BOLEPIX
          description: Allowed payment methods
          example:
            - PIX
        organization_id:
          type: string
          description: Associated organization ID
          example: a3dbd0c2-9f79-4f86-8caa-47779b3f2793
        anticipation_type:
          type: string
          enum:
            - AUTOMATIC
            - SPOT
          description: Anticipation type for the affiliation
          example: AUTOMATIC
        anticipation_days:
          type: integer
          minimum: 1
          description: Number of days for anticipation
          example: 1
        gateway_mode:
          type: boolean
          description: >-
            Whether this is a gateway-mode affiliation (Rinne acts as a pure
            capture gateway; no settlement, splits, or ledger entries)
          example: false
        onboarding_documents:
          type: array
          description: List of onboarding documents associated with this affiliation
          items:
            $ref: '#/components/schemas/OnboardingDocumentResponse'
        company_snapshot:
          type:
            - object
            - 'null'
          description: >-
            Point-in-time snapshot of company data (with contact) at affiliation
            creation. Only included when include_company_snapshot=true query
            parameter is set.
        created_at:
          type: string
          format: date-time
          description: Creation timestamp in ISO 8601 format
          example: '2023-01-01T12:00:00.000Z'
        updated_at:
          type: string
          format: date-time
          description: Last update timestamp in ISO 8601 format
          example: '2023-01-01T12:00:00.000Z'
      required:
        - id
        - provider
        - merchant_id
        - status
        - enabled
        - company_id
        - allowed_capture_methods
        - allowed_payment_methods
        - organization_id
        - gateway_mode
        - onboarding_documents
        - created_at
        - updated_at
    PaginationResponse:
      type: object
      required:
        - page
        - limit
        - total
        - totalPages
        - hasNext
        - hasPrev
      properties:
        page:
          type: integer
          example: 1
        limit:
          type: integer
          example: 20
        total:
          type: integer
          example: 50
        totalPages:
          type: integer
          example: 3
        hasNext:
          type: boolean
          example: true
        hasPrev:
          type: boolean
          example: false
    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
    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
    BankAccount:
      type: object
      description: Bank account information for affiliation
      required:
        - id
        - bank_code
        - branch_number
        - account_number
        - account_holder_name
        - account_holder_document_number
        - ispb
      properties:
        id:
          type: string
          description: Bank account ID
          example: a2da4238-bdc2-47f9-b866-246cc87212d5
        bank_code:
          type: string
          description: Bank code
          example: '001'
        branch_number:
          type: string
          pattern: ^\d+$
          description: Branch number (digits only)
          example: '1234'
        account_number:
          type: string
          pattern: ^\d+$
          description: Account number (digits only)
          example: '567890'
        account_holder_name:
          type: string
          description: Account holder name
          example: John Doe
        account_holder_document_number:
          type: string
          description: CPF or CNPJ (11 or 14 digits)
          example: '81146431023'
        ispb:
          type: string
          description: ISPB code
          example: '00000000'
    SettlementBankAccountResponse:
      type: object
      description: Settlement bank account information in affiliation response
      required:
        - id
        - branch_number
        - account_number
        - account_type
        - account_holder_name
        - account_holder_document_number
        - ispb
        - status
        - created_at
        - updated_at
      properties:
        id:
          type: string
          description: Settlement bank account ID
          example: b3eb5349-cec3-48fa-c977-357dd98323e6
        branch_number:
          type: string
          description: Branch number
          example: '1234'
        account_number:
          type: string
          description: Account number
          example: '567890'
        account_type:
          type: string
          enum:
            - CHECKING
            - SAVINGS
            - SALARY
            - PAYMENT
          description: Type of bank account
          example: CHECKING
        account_holder_name:
          type: string
          description: Account holder name
          example: John Doe
        account_holder_document_number:
          type: string
          description: CPF or CNPJ (11 or 14 digits)
          example: '81146431023'
        ispb:
          type: string
          description: ISPB code
          example: '00000000'
        status:
          type: string
          enum:
            - ACTIVE
            - PENDING_VALIDATION
            - VALIDATION_FAILED
            - FAILED
            - DISABLED
          description: >
            Settlement bank account validation status.

            ACTIVE: currently in use for settlements.

            PENDING_VALIDATION: sent to provider, awaiting async validation.

            VALIDATION_FAILED: provider rejected the bank account during async
            validation.

            FAILED: unrecoverable error (provider 4xx or timeout).

            DISABLED: superseded by a newly validated account.
          example: ACTIVE
        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'
    OnboardingDocumentResponse:
      type: object
      description: Onboarding document metadata (without download URL)
      properties:
        id:
          type: string
          description: Document unique identifier
          example: c5fdf2e4-1b9b-6108-aece-69991d5h4905
        file_type:
          type: string
          description: Type of document (e.g., CNH_FRONT, SELFIE, CONTRATO_SOCIAL)
          example: CNH_FRONT
        file_name:
          type: string
          description: Generated filename in storage
          example: CNH_FRONT_a1b2c3d4.pdf
        content_type:
          type:
            - string
            - 'null'
          description: MIME type of the document
          example: application/pdf
        file_size_bytes:
          type:
            - integer
            - 'null'
          description: File size in bytes
          example: 125430
        created_at:
          type: string
          format: date-time
          description: When the document was stored
          example: '2023-06-15T14:30:00.000Z'
      required:
        - id
        - file_type
        - file_name
        - created_at
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Company API key for authentication

````