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

# Reserve an inbound Pix Automático debit hold

> Reserves a debit HOLD on the payer's transactional account for a scheduled Pix Automático payment. Upstream calls this when it begins processing the scheduled payment. The reserve is parameterizable and disabled by default. On insufficient funds the result is returned inline (200) as a resultado=0 outcome with motivo SGCTPIX001, never an HTTP error.



## OpenAPI

````yaml en/openapi/v3-current/pix.yaml POST /v1/pix-automatico/settlements/inbound/block
openapi: 3.0.3
info:
  title: Plugin BR Pix Direct - Complete API
  description: |
    Complete API for Brazilian Pix instant payment system including
    Pix key dictionary operations, QR code generation/decoding, transactions and
    transaction limits.
  version: 1.0.0
servers:
  - url: https://plugin-pix-direct.api.lerian.net
  - url: https://plugin-pix-direct-qrcode.api.lerian.net
security:
  - bearerAuth: []
paths:
  /v1/pix-automatico/settlements/inbound/block:
    post:
      tags:
        - Pix Automático API
      summary: Reserve an inbound Pix Automático debit hold
      description: >-
        Reserves a debit HOLD on the payer's transactional account for a
        scheduled Pix Automático payment. Upstream calls this when it begins
        processing the scheduled payment. The reserve is parameterizable and
        disabled by default. On insufficient funds the result is returned inline
        (200) as a resultado=0 outcome with motivo SGCTPIX001, never an HTTP
        error.
      parameters:
        - description: >-
            Bearer access token (the financial-ingress gate; the handler fails
            closed with Pix-0082 when absent).
          in: header
          name: Authorization
          schema:
            description: >-
              Bearer access token (the financial-ingress gate; the handler fails
              closed with Pix-0082 when absent).
            type: string
        - description: Idempotency key (= the endToEndId of the transaction). Mandatory per
          in: header
          name: Chave-Idempotencia
          required: true
          schema:
            description: >-
              Idempotency key (= the endToEndId of the transaction). Mandatory
              per
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BlockScheduleBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlockScheduleResponse'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
components:
  schemas:
    BlockScheduleBody:
      additionalProperties: false
      properties:
        codMunIbge:
          description: Payer IBGE municipality code (7 digits).
          format: int64
          type: integer
        cpfCnpj:
          description: Payer CPF or CNPJ (a v5.5.0 string).
          type: string
        endToEndId:
          description: Unique payment-instruction id (32-char).
          type: string
        ispb:
          description: Payer participant ISPB (8 digits, a v5.5.0 string).
          type: string
        nrAgencia:
          description: Payer branch (nrAgencia, 4 digits, string).
          type: string
        nrConta:
          description: Payer account number (nrConta, a string).
          type: string
        tpPessoa:
          description: Payer person type (0=Pessoa Fisica, 1=Pessoa Juridica).
          format: int64
          type: integer
        valor:
          description: Reserve amount in reais.
          format: double
          type: number
      required:
        - endToEndId
        - ispb
        - tpPessoa
        - cpfCnpj
        - nrConta
        - codMunIbge
        - valor
      type: object
    BlockScheduleResponse:
      additionalProperties: false
      properties:
        dtHrRespostaSgct:
          description: settlement-gateway response timestamp (UTC).
          type: string
        endToEndId:
          description: Unique payment-instruction id (32-char).
          type: string
        idOperacaoSgct:
          description: >-
            settlement-gateway block-operation id (GUID; present only when
            resultado=1).
          type: string
        motivo:
          description: >-
            Rejection reason (SGCTPIX001=insufficient funds, SGCTPIX999=other;
            present only when resultado=0).
          type: string
        motivoComplemento:
          description: Rejection detail (present only when resultado=0).
          type: string
        resultado:
          description: Block result (0=Rejeitado, 1=Aceito).
          format: int64
          type: integer
      required:
        - endToEndId
        - resultado
        - dtHrRespostaSgct
      type: object
    Detail:
      additionalProperties: false
      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.
          type: string
        errors:
          description: Optional list of individual error details
          items:
            $ref: '#/components/schemas/ErrorDetail'
          type: array
          nullable: true
        instance:
          description: >-
            A URI reference that identifies the specific occurrence of the
            problem.
          format: uri
          type: string
        status:
          description: HTTP status code
          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.
          type: string
        type:
          default: about:blank
          description: A URI reference to human-readable documentation for the error.
          format: uri
          type: string
      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
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        JWT Bearer token authentication. Obtain token from
        `/v1/login/oauth/access_token` endpoint

        using client credentials (clientId and clientSecret).


        Include token in Authorization header:

        `Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`


        Token expires after 3600 seconds (1 hour).

````