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

# End a declaration

> Ends declaration `{settled_participant_id}` on `validTo`, the last day it is in force, by recording a new version of it. The previous version is kept. `validTo` is required, cannot be null, and is the only field that changes. A `validTo` one day before `validFrom` voids the declaration: it is never in force, the close and the overlap check skip it, and the ISPB can be declared again from any day. A later `validTo` puts it back in force. The same `validTo` as the current version creates no version and answers `200` with it.

A `validTo` earlier than the day before `validFrom`, or one that makes the validity overlap another declaration of the same ISPB, answers `422` (`PIX-0719`) at `body.validTo`. No declaration with this id answers `404` (`PIX-0722`), and an id that is not a UUID answers `400` (`PIX-0015`).

`version` is the current version of the declaration, as the last response for it gave it. Another version answers `409` (`PIX-0728`), and nothing is written. 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 /en/openapi/v3-current/pix-lerian-spi.yaml post /regulatory/apix/settled-participants/{settled_participant_id}/end
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/{settled_participant_id}/end:
    post:
      tags:
        - APIX Settled Participants
      summary: End a declaration
      description: >-
        Ends declaration `{settled_participant_id}` on `validTo`, the last day
        it is in force, by recording a new version of it. The previous version
        is kept. `validTo` is required, cannot be null, and is the only field
        that changes. A `validTo` one day before `validFrom` voids the
        declaration: it is never in force, the close and the overlap check skip
        it, and the ISPB can be declared again from any day. A later `validTo`
        puts it back in force. The same `validTo` as the current version creates
        no version and answers `200` with it.


        A `validTo` earlier than the day before `validFrom`, or one that makes
        the validity overlap another declaration of the same ISPB, answers `422`
        (`PIX-0719`) at `body.validTo`. No declaration with this id answers
        `404` (`PIX-0722`), and an id that is not a UUID answers `400`
        (`PIX-0015`).


        `version` is the current version of the declaration, as the last
        response for it gave it. Another version answers `409` (`PIX-0728`), and
        nothing is written. 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: endSettledParticipant
      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
        - description: >-
            id of the declaration, stable across its versions. Not a UUID is 400
            PIX-0015.
          in: path
          name: settled_participant_id
          required: true
          schema:
            description: >-
              id of the declaration, stable across its versions. Not a UUID is
              400 PIX-0015.
            examples:
              - 0193a7d0-1a2b-7c3d-8e4f-5a6b7c8d9e0f
            format: uuid
            type: string
      requestBody:
        content:
          application/json:
            examples: {}
            schema:
              $ref: '#/components/schemas/ApixEndSettledParticipantInput'
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                id: 0193a7d0-1a2b-7c3d-8e4f-5a6b7c8d9e0f
                version: 2
                ispb: '23456789'
                name: Exemplo Pagamentos IP S.A.
                validFrom: '2026-11-01'
                validTo: '2027-01-31'
              schema:
                $ref: '#/components/schemas/ApixSettledParticipant'
          description: OK
          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: validTo is required
                        location: body.validTo
                    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: validTo is malformed
                        location: body.validTo
                    code: PIX-0003
                PIX-0015:
                  value:
                    type: https://errors.lerian.studio/v1/PIX-0015
                    title: Bad Request
                    status: 400
                    detail: One or more path parameters are invalid.
                    errors:
                      - message: settled_participant_id must be a valid UUID
                        location: settled_participant_id
                    code: PIX-0015
              schema:
                $ref: '#/components/schemas/Detail'
          description: >-
            `validTo` or `version` absent (PIX-0002), `validTo` null or not
            YYYY-MM-DD, `version` below 1, or a field outside the schema
            (PIX-0003), or `settled_participant_id` not a UUID (PIX-0015).
            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.
        '404':
          content:
            application/json:
              example:
                code: TENANT_NOT_FOUND
                title: Tenant Not Found
                message: 'tenant not found: 019606a1-3b4c-7d8e-9f01-234567890abc'
              schema:
                $ref: '#/components/schemas/LegacyErrorEnvelope'
            application/problem+json:
              examples:
                PIX-0722:
                  value:
                    type: https://errors.lerian.studio/v1/PIX-0722
                    title: Not Found
                    status: 404
                    detail: No declaration with this id.
                    code: PIX-0722
              schema:
                $ref: '#/components/schemas/Detail'
          description: >-
            No declaration with this id (PIX-0722). 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.
        '409':
          content:
            application/problem+json:
              examples:
                PIX-0728:
                  value:
                    type: https://errors.lerian.studio/v1/PIX-0728
                    title: Conflict
                    status: 409
                    detail: >-
                      The declaration is not at the version sent. Send its
                      current version.
                    errors:
                      - message: version 1 is not the current version 2
                        location: body.version
                    code: PIX-0728
              schema:
                $ref: '#/components/schemas/Detail'
          description: >-
            `version` is not the declaration's current version, which the
            message names (PIX-0728).
        '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:
                  value:
                    type: https://errors.lerian.studio/v1/PIX-0719
                    title: Unprocessable Entity
                    status: 422
                    detail: The settled participant declaration is invalid.
                    errors:
                      - message: validTo is not valid for this declaration
                        location: body.validTo
                    code: PIX-0719
                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: >-
                          validTo overlaps settled participant declaration
                          0193a7c4-5e6f-7a8b-9c0d-1e2f3a4b5c6d
                        location: body.validTo
                    code: PIX-0719
              schema:
                $ref: '#/components/schemas/Detail'
          description: >-
            `validTo` earlier than the day before `validFrom`, or a validity
            that overlaps another declaration of the same ISPB, 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:
    ApixEndSettledParticipantInput:
      additionalProperties: false
      properties:
        validTo:
          description: >-
            Last day the declaration is in force, inclusive, YYYY-MM-DD;
            required and never null.
          examples:
            - '2027-01-31'
          format: date
          type: string
        version:
          description: >-
            Current version of the declaration, as its last response gave it;
            another version is 409 PIX-0728.
          examples:
            - 1
          format: int64
          minimum: 1
          type: integer
      required:
        - validTo
        - version
      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.