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

# Declare an indirect participant the tenant settles

> Declares an indirect participant (`ispb`) that the tenant settles for, in force from `validFrom`, with no end until you end it with the end route. The `id` of the response addresses the declaration from then on.

A close classifies each settlement outside SPI by the declarations in force at its cutoff. When both ISPBs are the tenant's, the settlement is `transactionDetail` 6. When one ISPB is the tenant's or the one of a declared indirect participant, for the civil day of `settledAt`, it is `transactionDetail` 5. Any other pair stays out of the rows.

The tenant's own ISPB (`body.ispb`), or a validity that overlaps another declaration of the same ISPB (`body.validFrom`), answers `422` (`PIX-0719`). The message of an overlap names the id of the declaration it meets. A declaration that starts after the last day of an earlier one, or of one voided, is accepted.

The optional `clientRequestId` keys the declaration per tenant. The same body under it answers the current declaration and creates nothing. Another body under it answers `409` (`PIX-0717`). A declaration, an end or a void that covers a closed month leaves that month's report unchanged. It enters only the close that follows a reopen.



## OpenAPI

````yaml /es/openapi/v3-current/pix-lerian-spi.yaml post /regulatory/apix/settled-participants
openapi: 3.1.0
info:
  contact:
    name: Lerian Studio
    url: https://lerian.studio
  description: Public API for outbound Pix transfers, refunds, and scheduled payments.
  license:
    name: Lerian Studio General License
  title: Pix Lerian — Payments
  version: 1.5.0
servers:
  - url: https://api.example.com/spi/v1
    description: >-
      Replace the example host with the URL provided during environment
      onboarding.
security:
  - BearerAuth: []
tags:
  - description: Create, list, and retrieve Pix refunds.
    name: Refunds
  - name: Scheduled Payments
    description: Register, list, retrieve, and cancel scheduled Pix payments.
  - description: >-
      Initiate, process, list, and retrieve outbound Pix transfers, and cancel
      or decide a sent Pix held in fraud analysis.
    name: Transfers
  - description: >-
      Register, list, retrieve, and cancel recurring series of scheduled Pix
      payments.
    name: Scheduled Payment Recurrences
  - description: >-
      Hold the funds of a received Pix in a cautionary block (MED 2.0), return
      them to the payer, or give them back to the account holder.
    name: Balance Locks
  - description: Read the APIX001 report of a closed month.
    name: APIX001 Reports
  - description: Close a reference month into an immutable report, and reopen it.
    name: APIX001 Periods
  - description: >-
      Record and correct the facts that only the participant knows, for the
      APIX001 report.
    name: APIX Client Facts
  - description: >-
      Declare the indirect participants that the tenant settles for, and end the
      declarations.
    name: APIX Settled Participants
paths:
  /regulatory/apix/settled-participants:
    post:
      tags:
        - APIX Settled Participants
      summary: Declare an indirect participant the tenant settles
      description: >-
        Declares an indirect participant (`ispb`) that the tenant settles for,
        in force from `validFrom`, with no end until you end it with the end
        route. The `id` of the response addresses the declaration from then on.


        A close classifies each settlement outside SPI by the declarations in
        force at its cutoff. When both ISPBs are the tenant's, the settlement is
        `transactionDetail` 6. When one ISPB is the tenant's or the one of a
        declared indirect participant, for the civil day of `settledAt`, it is
        `transactionDetail` 5. Any other pair stays out of the rows.


        The tenant's own ISPB (`body.ispb`), or a validity that overlaps another
        declaration of the same ISPB (`body.validFrom`), answers `422`
        (`PIX-0719`). The message of an overlap names the id of the declaration
        it meets. A declaration that starts after the last day of an earlier
        one, or of one voided, is accepted.


        The optional `clientRequestId` keys the declaration per tenant. The same
        body under it answers the current declaration and creates nothing.
        Another body under it answers `409` (`PIX-0717`). A declaration, an end
        or a void that covers a closed month leaves that month's report
        unchanged. It enters only the close that follows a reopen.
      operationId: declareSettledParticipant
      parameters:
        - description: >-
            REQUIRED. Client-supplied replay key, at most 64 bytes. A request
            without it is refused with PIX-0030 @ 400 before the handler runs.
            An identical resend within 1 hour returns the original response,
            status included, with X-Idempotency-Replayed: true. Reusing the key
            with a divergent method, URL or body is PIX-0031 @ 412.
          in: header
          name: X-Idempotency
          required: true
          schema:
            maxLength: 64
            minLength: 1
            type: string
      requestBody:
        content:
          application/json:
            examples: {}
            schema:
              $ref: '#/components/schemas/ApixSettledParticipantInput'
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                id: 0193a7d0-1a2b-7c3d-8e4f-5a6b7c8d9e0f
                version: 1
                ispb: '23456789'
                name: Exemplo Pagamentos IP S.A.
                validFrom: '2026-11-01'
                validTo: null
              schema:
                $ref: '#/components/schemas/ApixSettledParticipant'
          description: Created
          headers:
            X-Idempotency-Fenced:
              description: >-
                Present only when the request committed but its receipt could
                not be stored. true: a resend under the key within the hour is
                412 PIX-0031, so read the resource instead. false: a resend
                under the key may run again.
              schema:
                enum:
                  - 'true'
                  - 'false'
                type: string
            X-Idempotency-Replayed:
              description: >-
                true when the idempotency gate answered from the receipt of an
                earlier request under the same X-Idempotency; absent on a first
                execution.
              schema:
                enum:
                  - 'true'
                type: string
        '400':
          content:
            application/json:
              example:
                code: PIX-0030
                title: Idempotency Key Required
                message: >-
                  The X-Idempotency header is required for this operation and
                  must be within the accepted length.
              schema:
                $ref: '#/components/schemas/LegacyErrorEnvelope'
            application/problem+json:
              examples:
                PIX-0002:
                  value:
                    type: https://errors.lerian.studio/v1/PIX-0002
                    title: Bad Request
                    status: 400
                    detail: Your request is missing one or more required fields.
                    errors:
                      - message: validFrom is required
                        location: body.validFrom
                    code: PIX-0002
                PIX-0003:
                  value:
                    type: https://errors.lerian.studio/v1/PIX-0003
                    title: Bad Request
                    status: 400
                    detail: >-
                      Your request contains one or more fields with an invalid
                      data type.
                    errors:
                      - message: validFrom is malformed
                        location: body.validFrom
                    code: PIX-0003
              schema:
                $ref: '#/components/schemas/Detail'
          description: >-
            `ispb` or `validFrom` absent (PIX-0002), or a field with an invalid
            value or outside the schema (PIX-0003). X-Idempotency absent or
            longer than 64 bytes (PIX-0030). Legacy {code,title,message}
            envelope, NOT problem+json. Route-guard refusals (PIX-0010) answer
            in the legacy {code,title,message} envelope too.
        '401':
          description: >-
            Missing, malformed or expired bearer token, refused ahead of this
            operation by the authorization middleware in the legacy
            {code,title,message} envelope over application/json, with the
            generic client-error code PIX-0010. In a multi-tenant deployment the
            tenant middleware refuses a token it cannot read, or one with no
            usable tenantId claim, in the same shape with a code outside the
            PIX-NNNN catalogue: MISSING_TOKEN, INVALID_TOKEN, MISSING_TENANT or
            INVALID_TENANT. Branch on the status, not the body code.
        '403':
          content:
            application/problem+json:
              examples:
                PIX-0005:
                  value:
                    type: https://errors.lerian.studio/v1/PIX-0005
                    title: Forbidden
                    status: 403
                    detail: You do not have permission to perform this operation.
                    errors:
                      - message: >-
                          the token names no identity lib-auth can attribute; an
                          operator conclusion records who concluded, so it
                          requires one
                        location: principal
                    code: PIX-0005
              schema:
                $ref: '#/components/schemas/Detail'
          description: >-
            With authorization on, a token that names no identity that Access
            Manager can attribute (PIX-0005, errors[] at principal): each
            declaration version records who declared or ended it, so nothing was
            read or written. The token lacks the permission this operation's
            resource and action require, refused ahead of it by the
            authorization middleware in the legacy {code,title,message} envelope
            over application/json, with the generic client-error code PIX-0010.
            The tenant middlewares also answer 403 with a code outside the
            PIX-NNNN catalogue: TENANT_SUSPENDED or TENANT_ACCESS_DENIED in a
            multi-tenant deployment, in the same shape, and
            TENANT_CONFIG_NOT_FOUND, in a {code,message} body, when the tenant's
            configuration cannot be resolved. Branch on the status, not the body
            code.
        '409':
          content:
            application/problem+json:
              examples:
                PIX-0717:
                  value:
                    type: https://errors.lerian.studio/v1/PIX-0717
                    title: Conflict
                    status: 409
                    detail: >-
                      This clientRequestId is already recorded with different
                      content.
                    code: PIX-0717
              schema:
                $ref: '#/components/schemas/Detail'
          description: '`clientRequestId` already declared with another body (PIX-0717).'
        '412':
          content:
            application/json:
              example:
                code: PIX-0031
                title: Idempotency Key Conflict
                message: >-
                  The X-Idempotency header is held by a request still running or
                  whose receipt could not be stored, or was already used with a
                  different request.
              schema:
                $ref: '#/components/schemas/LegacyErrorEnvelope'
          description: >-
            Refused under this X-Idempotency (PIX-0031): the first request under
            it is still running (with Retry-After: 1), its receipt could not be
            stored and the key is held for the hour, or the request differs from
            the first (method, URL, body or identity header). An earlier request
            under this key may already have executed. Legacy
            {code,title,message} envelope, NOT problem+json.
        '413':
          content:
            application/json:
              example:
                code: PIX-0034
                title: Payload Too Large
                message: >-
                  The request body exceeds the maximum size allowed for this
                  operation.
              schema:
                $ref: '#/components/schemas/LegacyErrorEnvelope'
          description: >-
            A body over 1 KiB (PIX-0034). Route-guard refusals (PIX-0034) answer
            in the legacy {code,title,message} envelope over application/json,
            NOT problem+json.
        '415':
          content:
            application/json:
              example:
                code: PIX-0016
                title: Unsupported Media Type
                message: >-
                  The request body must be sent with Content-Type:
                  application/json.
              schema:
                $ref: '#/components/schemas/LegacyErrorEnvelope'
          description: >-
            The non-empty request body is missing an accepted JSON Content-Type
            (PIX-0016), answered in the legacy {code,title,message} envelope
            over application/json, NOT problem+json.
        '422':
          content:
            application/problem+json:
              examples:
                PIX-0719-overlap:
                  value:
                    type: https://errors.lerian.studio/v1/PIX-0719
                    title: Unprocessable Entity
                    status: 422
                    detail: The settled participant declaration is invalid.
                    errors:
                      - message: >-
                          validFrom overlaps settled participant declaration
                          0193a7c4-5e6f-7a8b-9c0d-1e2f3a4b5c6d
                        location: body.validFrom
                    code: PIX-0719
                PIX-0719-own-ispb:
                  value:
                    type: https://errors.lerian.studio/v1/PIX-0719
                    title: Unprocessable Entity
                    status: 422
                    detail: The settled participant declaration is invalid.
                    errors:
                      - message: ispb is not valid for this declaration
                        location: body.ispb
                    code: PIX-0719
              schema:
                $ref: '#/components/schemas/Detail'
          description: >-
            The tenant's own ISPB (`body.ispb`), or a validity that overlaps
            another declaration of the same ISPB (`body.validFrom`, whose
            message names that declaration's id) (PIX-0719).
        '500':
          content:
            application/json:
              example:
                code: PIX-0000
                title: Internal Server Error
                message: >-
                  The server encountered an unexpected error. Please try again
                  later.
              schema:
                $ref: '#/components/schemas/LegacyErrorEnvelope'
            application/problem+json:
              examples:
                PIX-0000:
                  value:
                    type: https://errors.lerian.studio/v1/PIX-0000
                    title: Internal Server Error
                    status: 500
                    detail: >-
                      The server encountered an unexpected error. Please try
                      again later.
                    code: PIX-0000
              schema:
                $ref: '#/components/schemas/Detail'
          description: >-
            Unexpected server error (PIX-0000). The middleware ahead of this
            operation answers this status too (see default), in the legacy
            {code,title,message} envelope over application/json, NOT
            problem+json.
        '503':
          content:
            application/json:
              example:
                code: PIX-0032
                title: Idempotency Unavailable
                message: >-
                  The request was not processed because the idempotency store is
                  unavailable. Please retry.
              schema:
                $ref: '#/components/schemas/LegacyErrorEnvelope'
          description: >-
            Replay cache unavailable on this fail-closed route, so the mutation
            was refused rather than executed without replay protection
            (PIX-0032). Legacy {code,title,message} envelope, NOT problem+json.
        default:
          content:
            application/json:
              example:
                code: PIX-0000
                title: Internal Server Error
                message: >-
                  The server encountered an unexpected error. Please try again
                  later.
              schema:
                $ref: '#/components/schemas/LegacyErrorEnvelope'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: >-
            Error. Middleware ahead of this operation also refuses in the legacy
            {code,title,message} envelope over application/json: a body over the
            server's 4 MiB limit with 413 PIX-0010; a query value holding the
            NUL character (%00) or invalid UTF-8 with 400 PIX-0020; the Access
            Manager unavailable (503) or timing out (504) with PIX-0000; and, in
            a multi-tenant deployment, the tenant middleware with 404
            TENANT_NOT_FOUND, 500 TENANT_DB_ERROR, 503
            TENANT_MANAGER_UNAVAILABLE or SERVICE_UNAVAILABLE, and 504
            TENANT_MANAGER_TIMEOUT. Branch on the status; these middleware 503
            and 504 refusals are retryable. Any operation that uses the database
            also answers 503 PIX-0062 when its Postgres connection is lost; that
            request may or may not have been processed, so repeat it only as
            this operation's own guidance for an unknown outcome allows.
components:
  schemas:
    ApixSettledParticipantInput:
      additionalProperties: false
      properties:
        clientRequestId:
          description: >-
            Client key of the declaration, unique per tenant: a resend with the
            same body answers the declaration it made, another body is 409
            PIX-0717. Not returned in the response.
          examples:
            - sp-2026-11-23456789
          maxLength: 64
          minLength: 1
          pattern: ^[A-Za-z0-9._:-]+$
          type: string
        ispb:
          description: >-
            ISPB of the indirect participant the tenant settles for, eight
            digits or uppercase letters; the tenant's own ISPB is 422 PIX-0719.
          examples:
            - '23456789'
          pattern: ^[0-9A-Z]{8}$
          type: string
        name:
          description: Name of the indirect participant, at most 140 characters.
          examples:
            - Exemplo Pagamentos IP S.A.
          maxLength: 140
          type: string
        validFrom:
          description: First day the declaration is in force, YYYY-MM-DD.
          examples:
            - '2026-11-01'
          format: date
          type: string
      required:
        - ispb
        - validFrom
      type: object
    ApixSettledParticipant:
      additionalProperties: false
      properties:
        id:
          description: Declaration id, stable across versions.
          examples:
            - 0193a7d0-1a2b-7c3d-8e4f-5a6b7c8d9e0f
          format: uuid
          type: string
        ispb:
          description: ISPB of the indirect participant the tenant settles for.
          examples:
            - '23456789'
          pattern: ^[0-9A-Z]{8}$
          type: string
        name:
          description: Name of the indirect participant, when declared.
          examples:
            - Exemplo Pagamentos IP S.A.
          type:
            - string
            - 'null'
        validFrom:
          description: First day the declaration is in force.
          examples:
            - '2026-11-01'
          format: date
          type: string
        validTo:
          description: >-
            Last day the declaration is in force, inclusive; null while it has
            no end.
          examples:
            - '2027-01-31'
          format: date
          type:
            - string
            - 'null'
        version:
          description: >-
            Version of the declaration: 1 when declared, one more when it is
            ended.
          examples:
            - 1
          format: int64
          minimum: 1
          type: integer
      required:
        - id
        - version
        - ispb
        - validFrom
        - validTo
      type: object
    LegacyErrorEnvelope:
      additionalProperties: false
      properties:
        code:
          description: PIX-XXXX error code
          type: string
        message:
          description: Human-readable error message
          type: string
        title:
          description: Short error title
          type: string
        fields:
          additionalProperties:
            type: string
          description: Per-field detail, keyed by the field or header the refusal names
          type: object
        headers:
          additionalProperties:
            type: string
          description: Per-header detail, keyed by the request header the refusal names
          type: object
      required:
        - code
        - title
        - message
      type: object
    Detail:
      additionalProperties: true
      properties:
        code:
          description: >-
            Stable, machine-readable domain error code scoped to the emitting
            service (format: <SERVICE>-NNNN).
          type: string
        detail:
          description: >-
            A human-readable explanation specific to this occurrence of the
            problem.
          examples:
            - Property foo is required but is missing.
          type: string
        errors:
          description: Optional list of individual error details
          items:
            $ref: '#/components/schemas/ErrorDetail'
          type:
            - array
            - 'null'
        instance:
          description: >-
            A URI reference that identifies the specific occurrence of the
            problem.
          examples:
            - https://example.com/error-log/abc123
          format: uri
          type: string
        status:
          description: HTTP status code
          examples:
            - 400
          format: int64
          type: integer
        title:
          description: >-
            A short, human-readable summary of the problem type. This value
            should not change between occurrences of the error.
          examples:
            - Bad Request
          type: string
        type:
          default: about:blank
          description: A URI reference to human-readable documentation for the error.
          examples:
            - https://example.com/errors/example
          format: uri
          type: string
        upstream:
          $ref: '#/components/schemas/Upstream'
          description: >-
            RFC 9457 extension member: the error a proxied third-party provider
            reported. Absent unless the emitting service explicitly surfaced
            one.
      type: object
    ErrorDetail:
      additionalProperties: false
      properties:
        location:
          description: >-
            Where the error occurred, e.g. 'body.items[3].tags' or
            'path.thing-id'
          type: string
        message:
          description: Error message text
          type: string
        value:
          description: The value at the given location
      type: object
    Upstream:
      additionalProperties: false
      properties:
        code:
          description: The upstream provider's own error code, verbatim.
          examples:
            - E4001
          type: string
        message:
          description: >-
            The upstream provider's own error message, verbatim (bounded, never
            its raw response body).
          examples:
            - account not found at provider
          type: string
      type: object
  securitySchemes:
    BearerAuth:
      bearerFormat: JWT
      description: JWT bearer token issued by the identity provider.
      scheme: bearer
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.