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

> Creates a new affiliation for the authenticated company. The company_id is automatically set from the authenticated client.
Requires the affiliation.create permission.




## OpenAPI

````yaml /api-spec.yaml post /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:
    post:
      tags:
        - Company Affiliations
      summary: Create new affiliation
      description: >
        Creates a new affiliation for the authenticated company. The company_id
        is automatically set from the authenticated client.

        Requires the affiliation.create permission.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AffiliationCreateRequest'
            example:
              provider: CELCOIN
              allowed_capture_methods:
                - EMV
                - CONTACTLESS_ICC
                - ECOMMERCE
              allowed_payment_methods:
                - CREDIT_CARD
                - DEBIT_CARD
                - PIX
      responses:
        '201':
          description: Affiliation created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliationResponse'
        '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 - Company already has affiliation with this provider
          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:
    AffiliationCreateRequest:
      type: object
      description: Schema for creating a new affiliation
      required:
        - provider
        - allowed_capture_methods
        - allowed_payment_methods
      properties:
        provider:
          type: string
          enum:
            - CELCOIN
            - RINNE
            - CAPPTA
          description: >-
            Payment provider name (accepts lowercase and uppercase, returns
            uppercase)
          example: CELCOIN
        allowed_capture_methods:
          type: array
          items:
            type: string
            enum:
              - EMV
              - MAGSTRIPE
              - ECOMMERCE
              - CONTACTLESS_ICC
          description: Allowed capture methods (at least one required)
          example:
            - EMV
            - CONTACTLESS_ICC
            - ECOMMERCE
          minItems: 1
        allowed_payment_methods:
          type: array
          items:
            type: string
            enum:
              - CREDIT_CARD
              - DEBIT_CARD
              - PIX
              - BOLEPIX
          description: Allowed payment methods (at least one required)
          example:
            - CREDIT_CARD
            - DEBIT_CARD
            - PIX
          minItems: 1
        settlement_bank_account:
          $ref: '#/components/schemas/SettlementBankAccountRequest'
          description: >
            External bank account for fund settlements.

            Required for RINNE and CAPPTA providers. Not required for CELCOIN
            (managed internally).
        anticipation_type:
          type: string
          enum:
            - AUTOMATIC
            - SPOT
          description: >-
            Anticipation type for the affiliation. Defaults to AUTOMATIC if not
            provided.
          default: AUTOMATIC
          example: AUTOMATIC
        anticipation_days:
          type: integer
          minimum: 1
          description: >-
            Number of days for automatic anticipation. Must be at least 1.
            Defaults to 1 if not provided.
          default: 1
          example: 1
    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
    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
    SettlementBankAccountRequest:
      type: object
      description: Settlement bank account request for affiliation creation
      required:
        - branch_number
        - account_number
        - account_type
        - ispb
      properties:
        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_type:
          type: string
          enum:
            - CHECKING
            - SAVINGS
            - SALARY
            - PAYMENT
          description: Type of bank account
          example: CHECKING
        ispb:
          type: string
          pattern: ^\d{8}$
          description: ISPB code (8 digits)
          example: '00000000'
    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

````