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

# Record a fact only the participant knows

> Records version 1 of a fact that only your institution knows, for the APIX001 report of a month. `fact_type` in the path selects the body, and the `factType` of the body must have the same value (`422`, `PIX-0723`).

The route accepts `OUTSIDE_SPI_SETTLEMENT`, `OUTSIDE_SPI_REFUND`, `OUTBOUND_FRAUD_REFUSAL` and `DICT_SCREEN_STEP`. The same `clientRequestId` with the same content creates nothing and answers the fact already recorded. The same `clientRequestId` with other content answers `409` (`PIX-0717`): correct the fact with the correct route. A new `clientRequestId` for a subject that already has a current fact of the same type answers `409` (`PIX-0725`). An `OUTSIDE_SPI_REFUND` needs a `reasonCode` of `FR01`, `MD06`, `SL02` or `BE08`, or the route answers `422` (`PIX-0726`). `FR01` counts as fraud (`refundDetail` 1). The other three count as other (`refundDetail` 2).

A fact for a closed month is accepted. It enters a report only after a reopen and a new close.

Pix Lerian limits recording and correcting facts to 2 in flight for each tenant on each serving instance. Above that, the route answers `429` (`PIX-0006`) with `Retry-After` and records nothing. Send a backfill one request at a time.



## OpenAPI

````yaml /en/openapi/v3-current/pix-lerian-spi.yaml post /regulatory/apix/facts/{fact_type}
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/facts/{fact_type}:
    post:
      tags:
        - APIX Client Facts
      summary: Record a fact only the participant knows
      description: >-
        Records version 1 of a fact that only your institution knows, for the
        APIX001 report of a month. `fact_type` in the path selects the body, and
        the `factType` of the body must have the same value (`422`, `PIX-0723`).


        The route accepts `OUTSIDE_SPI_SETTLEMENT`, `OUTSIDE_SPI_REFUND`,
        `OUTBOUND_FRAUD_REFUSAL` and `DICT_SCREEN_STEP`. The same
        `clientRequestId` with the same content creates nothing and answers the
        fact already recorded. The same `clientRequestId` with other content
        answers `409` (`PIX-0717`): correct the fact with the correct route. A
        new `clientRequestId` for a subject that already has a current fact of
        the same type answers `409` (`PIX-0725`). An `OUTSIDE_SPI_REFUND` needs
        a `reasonCode` of `FR01`, `MD06`, `SL02` or `BE08`, or the route answers
        `422` (`PIX-0726`). `FR01` counts as fraud (`refundDetail` 1). The other
        three count as other (`refundDetail` 2).


        A fact for a closed month is accepted. It enters a report only after a
        reopen and a new close.


        Pix Lerian limits recording and correcting facts to 2 in flight for each
        tenant on each serving instance. Above that, the route answers `429`
        (`PIX-0006`) with `Retry-After` and records nothing. Send a backfill one
        request at a time.
      operationId: recordApixClientFact
      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: >-
            Fact type, the same value as the `factType` of the body. One of
            OUTSIDE_SPI_SETTLEMENT, OUTSIDE_SPI_REFUND, OUTBOUND_FRAUD_REFUSAL
            or DICT_SCREEN_STEP. Any other value is refused.
          in: path
          name: fact_type
          required: true
          schema:
            description: >-
              Fact type, the same value as the `factType` of the body. One of
              OUTSIDE_SPI_SETTLEMENT, OUTSIDE_SPI_REFUND, OUTBOUND_FRAUD_REFUSAL
              or DICT_SCREEN_STEP. Any other value is refused.
            enum:
              - OUTBOUND_FRAUD_REFUSAL
              - OUTSIDE_SPI_SETTLEMENT
              - OUTSIDE_SPI_REFUND
              - DICT_SCREEN_STEP
            examples:
              - OUTSIDE_SPI_REFUND
            type: string
      requestBody:
        content:
          application/json:
            examples:
              dictScreenStep:
                summary: DICT_SCREEN_STEP
                value:
                  factType: DICT_SCREEN_STEP
                  clientRequestId: dss-2026-10-key-reg-0042-s6
                  operation: KEY_REGISTRATION
                  operationRef: 0193a5c1-9e8f-7a6b-8c5d-4e3f2a1b0c9d
                  step: 6
                  occurredAt: '2026-10-12T11:20:31.507Z'
              outboundFraudRefusal:
                summary: OUTBOUND_FRAUD_REFUSAL
                value:
                  factType: OUTBOUND_FRAUD_REFUSAL
                  clientRequestId: ofr-2026-10-000233
                  endToEndId: null
                  amount: '4800.00'
                  cashAmount: '0.00'
                  purpose: IPAY
                  refusedAt: '2026-10-21T22:47:13.880Z'
              outsideSpiRefund:
                summary: OUTSIDE_SPI_REFUND
                value:
                  factType: OUTSIDE_SPI_REFUND
                  clientRequestId: osr-2026-10-000071
                  endToEndId: D12345678202610311702a9b8c7d6e5f
                  originalEndToEndId: E12345678202610311545f6e5d4c3b2a
                  amount: '89.90'
                  reasonCode: MD06
                  settledAt: '2026-10-31T17:02:44.019Z'
              outsideSpiSettlement:
                summary: OUTSIDE_SPI_SETTLEMENT
                value:
                  factType: OUTSIDE_SPI_SETTLEMENT
                  clientRequestId: osp-2026-10-004512
                  endToEndId: E12345678202610311545f6e5d4c3b2a
                  amount: '89.90'
                  cashAmount: '0.00'
                  purpose: IPAY
                  payerIspb: '12345678'
                  receiverIspb: '12345678'
                  settledAt: '2026-10-31T15:45:10.958Z'
                  acceptedAt: '2026-10-31T15:45:10.412Z'
                  payerNotifiedAt: '2026-10-31T15:45:11.204Z'
                  highPriority: true
                  initiationChannel: APP
                  scheduled: false
                  fraudSuspected: false
                  initiationProcedure: MANUAL
                  initiationMechanism: KEY
                  payerPersonType: NATURAL_PERSON
                  receiverPersonType: LEGAL_PERSON
            schema:
              $ref: '#/components/schemas/ApixClientFactInput'
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                factId: 0193a7c2-5d4e-7f10-a2b3-c4d5e6f7a8b9
                factType: OUTSIDE_SPI_REFUND
                clientRequestId: osr-2026-10-000071
                version: 1
                period: 2026-10
                payload:
                  factType: OUTSIDE_SPI_REFUND
                  clientRequestId: osr-2026-10-000071
                  endToEndId: D12345678202610311702a9b8c7d6e5f
                  originalEndToEndId: E12345678202610311545f6e5d4c3b2a
                  amount: '89.90'
                  reasonCode: MD06
                  settledAt: '2026-10-31T17:02:44.019Z'
              schema:
                $ref: '#/components/schemas/ApixClientFact'
          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: endToEndId is required
                        location: body.endToEndId
                    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: cashAmount is malformed
                        location: body.cashAmount
                    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: is not an APIX fact type
                        location: fact_type
                    code: PIX-0015
              schema:
                $ref: '#/components/schemas/Detail'
          description: >-
            A required body field is missing (PIX-0002), or a body field has an
            invalid value (PIX-0003): a value outside its format, such as a
            `clientRequestId` outside its pattern or a malformed end-to-end id
            or a `reasonCode` not of four upper-case letters or digits, a `step`
            that is not an integer from 1 to 30 or an `operationRef` that is not
            a lowercase hyphenated UUID; a `cashAmount` outside the rule of its
            `purpose`; a `highPriority` of true on an OUTSIDE_SPI_SETTLEMENT
            with `purpose` AUTOMATIC, `scheduled` true or `fraudSuspected` true;
            or, on an OUTSIDE_SPI_SETTLEMENT whose `payerIspb` is the tenant, an
            absent `acceptedAt`, an absent or null `payerNotifiedAt`, or a
            `payerNotifiedAt` more than 999999.99 seconds after `acceptedAt`,
            the longest time the layout renders. `errors[].location` names the
            field, as `body.<field>`. Field names are case-sensitive: a field
            the type does not define, such as `Amount` for `amount`, is PIX-0003
            at `body`. A `fact_type` that is not an APIX fact type is PIX-0015
            at `fact_type`. 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':
          description: >-
            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
                PIX-0725:
                  value:
                    type: https://errors.lerian.studio/v1/PIX-0725
                    title: Conflict
                    status: 409
                    detail: >-
                      Another current fact of this type already covers the same
                      subject.
                    code: PIX-0725
              schema:
                $ref: '#/components/schemas/Detail'
          description: >-
            `clientRequestId` already recorded with different content
            (PIX-0717), or another `clientRequestId` for a subject that already
            has a current fact of this type (PIX-0725).
        '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 16 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-0723:
                  value:
                    type: https://errors.lerian.studio/v1/PIX-0723
                    title: Unprocessable Entity
                    status: 422
                    detail: The fact body does not match the path.
                    code: PIX-0723
                PIX-0724:
                  value:
                    type: https://errors.lerian.studio/v1/PIX-0724
                    title: Unprocessable Entity
                    status: 422
                    detail: This fact type is not accepted.
                    code: PIX-0724
                PIX-0726:
                  value:
                    type: https://errors.lerian.studio/v1/PIX-0726
                    title: Unprocessable Entity
                    status: 422
                    detail: >-
                      The refund reason code is not in the APIX refund reason
                      catalog.
                    errors:
                      - message: reasonCode is not in the APIX refund reason catalog
                        location: body.reasonCode
                    code: PIX-0726
              schema:
                $ref: '#/components/schemas/Detail'
          description: >-
            The body does not match the path (PIX-0723), the type is not
            accepted (PIX-0724), or an OUTSIDE_SPI_REFUND carries a `reasonCode`
            outside the APIX refund reason catalog FR01, MD06, SL02 and BE08
            (PIX-0726, errors[] at body.reasonCode).
        '429':
          content:
            application/problem+json:
              examples:
                PIX-0006:
                  value:
                    type: https://errors.lerian.studio/v1/PIX-0006
                    title: Too Many Requests
                    status: 429
                    detail: >-
                      Rate limit exceeded. Please wait before making additional
                      requests.
                    code: PIX-0006
              schema:
                $ref: '#/components/schemas/Detail'
          description: >-
            The tenant already has 2 facts in flight on the serving instance,
            records and corrections together (PIX-0006). Nothing was recorded
            and the gate freed the key: resend the identical request after
            Retry-After.
          headers:
            Retry-After:
              description: Seconds to wait before sending the same request again.
              schema:
                minimum: 1
                type: integer
        '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.
        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:
    ApixClientFactInput:
      description: Fact body, one schema per fact type chosen by `factType`.
      discriminator:
        mapping:
          DICT_SCREEN_STEP: '#/components/schemas/ApixDictScreenStepInput'
          OUTBOUND_FRAUD_REFUSAL: '#/components/schemas/ApixOutboundFraudRefusalInput'
          OUTSIDE_SPI_REFUND: '#/components/schemas/ApixOutsideSpiRefundInput'
          OUTSIDE_SPI_SETTLEMENT: '#/components/schemas/ApixOutsideSpiSettlementInput'
        propertyName: factType
      oneOf:
        - $ref: '#/components/schemas/ApixOutsideSpiSettlementInput'
        - $ref: '#/components/schemas/ApixOutboundFraudRefusalInput'
        - $ref: '#/components/schemas/ApixOutsideSpiRefundInput'
        - $ref: '#/components/schemas/ApixDictScreenStepInput'
    ApixClientFact:
      additionalProperties: false
      properties:
        clientRequestId:
          description: The participant's key of the fact, unique per tenant and fact type.
          examples:
            - cb-2026-10-000017
          type: string
        factId:
          description: Identifier of this version of the fact.
          examples:
            - 0193a7c2-5d4e-7f10-a2b3-c4d5e6f7a8b9
          format: uuid
          type: string
        factType:
          description: Fact type, as in the path.
          examples:
            - OUTSIDE_SPI_REFUND
          type: string
        payload:
          description: The fact body as recorded.
        period:
          description: Reference month the fact counts in, YYYY-MM.
          examples:
            - 2026-10
          type: string
        version:
          description: 'Version of the fact: 1 when recorded, one more per correction.'
          examples:
            - 1
          format: int64
          type: integer
      required:
        - factId
        - factType
        - clientRequestId
        - version
        - period
        - payload
      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
    ApixDictScreenStepInput:
      additionalProperties: false
      properties:
        clientRequestId:
          description: Client key of the fact, unique per fact type and tenant.
          examples:
            - dss-2026-10-key-reg-0042-s6
          maxLength: 64
          minLength: 1
          pattern: ^[A-Za-z0-9._:-]+$
          type: string
        factType:
          description: Fact type; must equal the path fact_type (422 PIX-0723).
          enum:
            - DICT_SCREEN_STEP
          examples:
            - DICT_SCREEN_STEP
          type: string
        occurredAt:
          description: >-
            Instant the step happened in the participant's channel, RFC 3339;
            its month in America/Sao_Paulo is the reference month, from 2020-11
            through the current month (400 PIX-0003).
          examples:
            - '2026-10-12T11:20:31.507Z'
          format: date-time
          type: string
        operation:
          description: DICT operation the step belongs to.
          enum:
            - KEY_REGISTRATION
            - KEY_DELETION
            - PORTABILITY
            - CLAIM
            - MED_OPENING
          examples:
            - KEY_REGISTRATION
          type: string
        operationRef:
          description: >-
            Pix Lerian id of the key entry, claim or funds recovery in the DICT
            hub, in lowercase hyphenated form. Not checked by the SPI. One
            current fact per operation, operationRef and step (409 PIX-0725).
          examples:
            - 0193a5c1-9e8f-7a6b-8c5d-4e3f2a1b0c9d
          format: uuid
          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
          type: string
        step:
          description: >-
            Step number of the DICT Operational Manual flow; every step from 1
            to 30 is accepted.
          examples:
            - 6
          format: int64
          maximum: 30
          minimum: 1
          type: integer
      required:
        - factType
        - clientRequestId
        - operation
        - operationRef
        - step
        - occurredAt
      type: object
    ApixOutboundFraudRefusalInput:
      additionalProperties: false
      properties:
        amount:
          description: >-
            Amount in BRL, greater than 0.00, up to 13 integer digits and
            exactly two decimal places.
          examples:
            - '4800.00'
          pattern: ^[0-9]{1,13}\.[0-9]{2}$
          type: string
        cashAmount:
          description: >-
            Cash part of the amount, absent as 0.00, under the purpose's rule as
            on OUTSIDE_SPI_SETTLEMENT.
          examples:
            - '0.00'
          pattern: ^[0-9]{1,13}\.[0-9]{2}$
          type: string
        clientRequestId:
          description: Client key of the fact, unique per fact type and tenant.
          examples:
            - ofr-2026-10-000233
          maxLength: 64
          minLength: 1
          pattern: ^[A-Za-z0-9._:-]+$
          type: string
        endToEndId:
          description: >-
            End-to-end id of the refused Pix, E prefix; absent or null when the
            Pix got none. With one, one current fact per end-to-end id (409
            PIX-0725).
          examples:
            - E12345678202610212247a1b2c3d4e5f
          pattern: ^E[0-9A-Z]{8}[0-9]{12}[A-Za-z0-9]{11}$
          type:
            - string
            - 'null'
        factType:
          description: Fact type; must equal the path fact_type (422 PIX-0723).
          enum:
            - OUTBOUND_FRAUD_REFUSAL
          examples:
            - OUTBOUND_FRAUD_REFUSAL
          type: string
        purpose:
          description: Transaction purpose, the layout's FinalidadeTransacoes.
          enum:
            - IPAY
            - OTHR
            - GSCB
            - AUTOMATIC
          examples:
            - IPAY
          type: string
        refusedAt:
          description: >-
            Refusal instant, RFC 3339; its month in America/Sao_Paulo is the
            reference month, from 2020-11 through the current month (400
            PIX-0003).
          examples:
            - '2026-10-21T22:47:13.880Z'
          format: date-time
          type: string
      required:
        - factType
        - clientRequestId
        - amount
        - purpose
        - refusedAt
      type: object
    ApixOutsideSpiRefundInput:
      additionalProperties: false
      properties:
        amount:
          description: >-
            Refunded amount in BRL, greater than 0.00, up to 13 integer digits
            and exactly two decimal places.
          examples:
            - '89.90'
          pattern: ^[0-9]{1,13}\.[0-9]{2}$
          type: string
        clientRequestId:
          description: Client key of the fact, unique per fact type and tenant.
          examples:
            - osr-2026-10-000071
          maxLength: 64
          minLength: 1
          pattern: ^[A-Za-z0-9._:-]+$
          type: string
        endToEndId:
          description: >-
            End-to-end id of the refund itself, D prefix; one current fact per
            end-to-end id (409 PIX-0725).
          examples:
            - D12345678202610311702a9b8c7d6e5f
          pattern: ^D[0-9A-Z]{8}[0-9]{12}[A-Za-z0-9]{11}$
          type: string
        factType:
          description: Fact type; must equal the path fact_type (422 PIX-0723).
          enum:
            - OUTSIDE_SPI_REFUND
          examples:
            - OUTSIDE_SPI_REFUND
          type: string
        originalEndToEndId:
          description: End-to-end id of the refunded transaction, E prefix.
          examples:
            - E12345678202610311545f6e5d4c3b2a
          pattern: ^E[0-9A-Z]{8}[0-9]{12}[A-Za-z0-9]{11}$
          type: string
        reasonCode:
          description: >-
            Refund reason from the APIX catalog: FR01 counts as fraud
            (refundDetail 1), the others as other refunds (refundDetail 2). Four
            uppercase letters or digits outside the catalog is 422 PIX-0726; any
            other value is 400 PIX-0003.
          enum:
            - FR01
            - MD06
            - SL02
            - BE08
          examples:
            - MD06
          type: string
        settledAt:
          description: >-
            Refund settlement instant, RFC 3339; its month in America/Sao_Paulo
            is the reference month, from 2020-11 through the current month (400
            PIX-0003).
          examples:
            - '2026-10-31T17:02:44.019Z'
          format: date-time
          type: string
      required:
        - factType
        - clientRequestId
        - endToEndId
        - originalEndToEndId
        - amount
        - reasonCode
        - settledAt
      type: object
    ApixOutsideSpiSettlementInput:
      additionalProperties: false
      properties:
        acceptedAt:
          description: >-
            Instant the payer's participant accepted the order. Required, and
            never null, when payerIspb is the tenant's ISPB; may be absent
            otherwise.
          examples:
            - '2026-10-31T15:45:10.412Z'
          format: date-time
          type: string
        amount:
          description: >-
            Amount in BRL, greater than 0.00, up to 13 integer digits and
            exactly two decimal places.
          examples:
            - '89.90'
          pattern: ^[0-9]{1,13}\.[0-9]{2}$
          type: string
        cashAmount:
          description: >-
            Cash part of the amount, absent as 0.00: zero for IPAY and
            AUTOMATIC, the whole amount for OTHR, more than zero and less than
            the amount for GSCB; otherwise 400 PIX-0003.
          examples:
            - '0.00'
          pattern: ^[0-9]{1,13}\.[0-9]{2}$
          type: string
        clientRequestId:
          description: Client key of the fact, unique per fact type and tenant.
          examples:
            - osp-2026-10-004512
          maxLength: 64
          minLength: 1
          pattern: ^[A-Za-z0-9._:-]+$
          type: string
        endToEndId:
          description: >-
            End-to-end id of the transaction, E prefix; one current fact per
            end-to-end id (409 PIX-0725).
          examples:
            - E12345678202610311545f6e5d4c3b2a
          pattern: ^E[0-9A-Z]{8}[0-9]{12}[A-Za-z0-9]{11}$
          type: string
        factType:
          description: Fact type; must equal the path fact_type (422 PIX-0723).
          enum:
            - OUTSIDE_SPI_SETTLEMENT
          examples:
            - OUTSIDE_SPI_SETTLEMENT
          type: string
        fraudSuspected:
          description: >-
            Whether fraud was suspected (APIX002); absent is false. When true,
            the settlement stays out of the outside-SPI times.
          examples:
            - false
          type: boolean
        highPriority:
          description: >-
            Neither scheduled, AUTOMATIC nor fraudSuspected. Absent is derived
            from those three; true with any of them is 400 PIX-0003.
          examples:
            - true
          type: boolean
        initiationChannel:
          description: Channel the payer used (APIX002).
          enum:
            - APP
            - INTERNET_BANKING
            - CALL_CENTER
            - ATM
            - BRANCH
          examples:
            - APP
          type: string
        initiationMechanism:
          description: How the payment was initiated (APIX002).
          enum:
            - KEY
            - DYNAMIC_QR
            - STATIC_QR
            - PAYMENT_INITIATOR
            - MANUAL
          examples:
            - KEY
          type: string
        initiationProcedure:
          description: How the payment data was entered (APIX002).
          enum:
            - MANUAL
            - PRE_STORED
          examples:
            - MANUAL
          type: string
        payerIspb:
          description: >-
            ISPB of the payer's participant. When it is the tenant's own ISPB,
            acceptedAt and payerNotifiedAt are required.
          examples:
            - '12345678'
          pattern: ^[0-9A-Z]{8}$
          type: string
        payerNotifiedAt:
          description: >-
            Instant the payer was notified of the result. Required and not null
            when payerIspb is the tenant's ISPB, not before acceptedAt and at
            most 999999.99 s after it (400 PIX-0003); may be absent or null
            otherwise.
          examples:
            - '2026-10-31T15:45:11.204Z'
          format: date-time
          type:
            - string
            - 'null'
        payerPersonType:
          description: Payer's person type (APIX002).
          enum:
            - NATURAL_PERSON
            - LEGAL_PERSON
          examples:
            - NATURAL_PERSON
          type: string
        paymentInitiatorIspb:
          description: >-
            ISPB of the payment initiator; only with initiationMechanism
            PAYMENT_INITIATOR, otherwise 400 PIX-0003.
          examples:
            - '87654321'
          pattern: ^[0-9A-Z]{8}$
          type: string
        purpose:
          description: Transaction purpose, the layout's FinalidadeTransacoes.
          enum:
            - IPAY
            - OTHR
            - GSCB
            - AUTOMATIC
          examples:
            - IPAY
          type: string
        receiverIspb:
          description: ISPB of the receiver's participant.
          examples:
            - '12345678'
          pattern: ^[0-9A-Z]{8}$
          type: string
        receiverPersonType:
          description: Receiver's person type (APIX002).
          enum:
            - NATURAL_PERSON
            - LEGAL_PERSON
          examples:
            - LEGAL_PERSON
          type: string
        scheduled:
          description: Whether the payment was scheduled; absent is false.
          examples:
            - false
          type: boolean
        settledAt:
          description: >-
            Settlement instant, RFC 3339; its month in America/Sao_Paulo is the
            reference month, from 2020-11 through the current month (400
            PIX-0003).
          examples:
            - '2026-10-31T15:45:10.958Z'
          format: date-time
          type: string
      required:
        - factType
        - clientRequestId
        - endToEndId
        - amount
        - purpose
        - payerIspb
        - receiverIspb
        - settledAt
      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.