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

# Consultar estado de un cobro

> Retorna el estado actual y los detalles de una sesión de cobro. Útil como fallback cuando el webhook aún no llegó pero el usuario ya regresó por redirect.

## ¿Para qué se usa?

Obtiene el estado actual y los detalles completos de una sesión de cobro. Útil como fallback cuando el webhook todavía no llegó pero el usuario ya regresó a tu sitio por redirect.

## Qué hace

* Retorna el estado actual de la sesión (`pending`, `paid`, `expired`).
* Incluye todos los campos de la sesión: monto, tipo de DTE, `auto_issue`, `external_id` y `metadata`.

## Ejemplos de uso

* **Verificar el estado al regresar del redirect**: El usuario vuelve a tu sitio y quieres confirmar si pagó antes de mostrarle la pantalla de confirmación.
* **Polling de respaldo**: Si por alguna razón no recibiste el webhook, puedes consultar el estado directamente.

## Consideraciones importantes

### Webhooks son la fuente primaria

El GET es un mecanismo de respaldo. El flujo recomendado es:

1. Recibir el webhook `payment_request.paid` y actualizar tu sistema.
2. Si no llegó el webhook en un tiempo razonable, consulta el GET.

<Info>
  El campo `issued_document_id` apunta al DTE emitido y puede usarse para consultar el documento en la API de Facturación.
</Info>


## OpenAPI

````yaml api-reference/openapi-payment-requests.json GET /payment-requests/{payment_request_id}/
openapi: 3.0.0
info:
  title: Tupana API - Recaudación
  description: >-
    API de Cobros — Crea sesiones de pago, procesa cobros y emite DTE
    automáticamente.
  version: 1.0.0
servers:
  - url: https://api.tupana.ai/v1
    description: Servidor de producción
security:
  - apiKeyAuth: []
paths:
  /payment-requests/{payment_request_id}/:
    get:
      tags:
        - Cobros
      summary: Consultar estado de un cobro
      description: >-
        Retorna el estado actual y los detalles de una sesión de cobro. Útil
        como fallback cuando el webhook aún no llegó pero el usuario ya regresó
        por redirect.
      operationId: getPaymentRequest
      parameters:
        - name: payment_request_id
          in: path
          required: true
          description: ID numérico de la sesión de cobro.
          schema:
            type: integer
      responses:
        '200':
          description: Datos de la sesión de cobro
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequestResponse'
              example:
                payment_request_id: 1042
                status: paid
                payment_url: https://www.tupana.ai/pagos/tok_xyz
                expires_at: '2026-04-06T12:30:00Z'
                created_at: '2026-04-06T12:00:00Z'
                amount: 50000
                target_dte_type: '39'
                auto_issue: true
                external_id: booking_abc123
                metadata: {}
                issued_document_id: null
                document_ids: []
        '401':
          description: API key inválida o no proporcionada
        '404':
          description: Sesión no encontrada o no pertenece a tu API key
      security:
        - apiKeyAuth: []
components:
  schemas:
    PaymentRequestResponse:
      type: object
      properties:
        payment_request_id:
          type: integer
          description: ID único de la sesión de cobro.
          example: 1042
        status:
          type: string
          enum:
            - pending
            - paid
            - issued
            - failed
            - expired
            - refunded
          example: pending
        payment_url:
          type: string
          format: uri
          description: URL a la que debes redirigir al usuario para que complete el pago.
          example: https://www.tupana.ai/pagos/tok_xyz
        expires_at:
          type: string
          format: date-time
          description: Fecha y hora en que vence la sesión (UTC).
          example: '2026-04-06T12:30:00Z'
        created_at:
          type: string
          format: date-time
          description: Fecha y hora de creación de la sesión (UTC).
          example: '2026-04-06T12:00:00Z'
        amount:
          type: number
          description: Monto del cobro en CLP.
          example: 50000
        target_dte_type:
          type: string
          nullable: true
          description: >-
            Tipo de DTE que se emitirá al pagarse. `null` en modo cobro directo
            (no hay DTE a emitir).
          example: '39'
        auto_issue:
          type: boolean
          nullable: true
          description: >-
            Si el DTE se emite automáticamente al confirmarse el pago. `null` en
            modo cobro directo.
          example: true
        external_id:
          type: string
          nullable: true
          description: Tu ID propio para esta sesión.
          example: booking_abc123
        metadata:
          type: object
          additionalProperties: true
          description: Datos adicionales que enviaste al crear la sesión.
        issued_document_id:
          type: integer
          nullable: true
          description: >-
            ID del DTE emitido. `null` mientras la sesión no haya emitido el
            DTE. Siempre `null` en modo cobro directo.
          example: 9871
        document_ids:
          type: array
          items:
            type: integer
          description: >-
            IDs de los documentos que esta sesión cobra. Lista vacía en modo
            emisión (donde el DTE se emite al pagarse).
          example:
            - 9871
            - 9872
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'API Key para autenticación. Formato: `Api-Key YOUR-API-KEY`'

````