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

# List Payments

> Lista pagos paginados con filtros opcionales.

Varios filtros aceptan múltiples valores separados por coma (ej. `beneficiary_reference=ref-1,ref-2`). Las fechas usan formato `YYYY-MM-DD` y aplican sobre la fecha de vencimiento del payable asociado.

Para obtener el detalle completo de un pago (incluyendo datos de contacto del beneficiario, centro de costo, proyectos e información del ERP) usá `GET /payments/{reference}`.



## OpenAPI

````yaml GET /payments
openapi: 3.1.0
info:
  title: Payana Accounts Payable API
  description: >-
    API pública para gestionar cuentas por pagar (payments) y beneficiarios
    (beneficiaries) en Payana, incluyendo notificaciones por webhooks cuando se
    procesan pagos.
  version: 1.0.0
servers:
  - url: https://api.prod.payana.cloud/public/api/v1
    description: Production
  - url: https://api.develop.payana.cloud/public/api/v1
    description: Develop
security:
  - apiKeyAuth: []
tags:
  - name: Payments
    description: Crear y listar pagos
  - name: Beneficiaries
    description: Crear, listar y consultar beneficiarios
  - name: Webhooks
    description: Eventos de webhooks enviados por Payana
  - name: Banks
    description: Listar y consultar bancos
  - name: Transactions In
    description: Transacciones entrantes (polling, mismo formato que webhooks)
  - name: Documents
    description: Listar, consultar y operar documentos (cuentas por pagar)
  - name: DIAN Events
    description: >-
      Encolar eventos DIAN (030 Acuse de recibo, 031 Reclamo, 032 Recibo del
      bien, 033 Aceptación expresa, 034 Aceptación tácita) para documentos
      identificados por CUFE. El procesamiento es asíncrono.
  - name: Fiscal Sync
    description: >-
      Disparar y consultar sincronización de documentos fiscales desde el SAT
      (México) o la DIAN (Colombia).
  - name: Workflow Steps
    description: >-
      Resolver el paso en que está parado un documento dentro de su flujo:
      aprobación, clasificación o etiquetado.
paths:
  /payments:
    get:
      tags:
        - Payments
      summary: List payments
      description: >-
        Lista pagos paginados con filtros opcionales.


        Varios filtros aceptan múltiples valores separados por coma (ej.
        `beneficiary_reference=ref-1,ref-2`). Las fechas usan formato
        `YYYY-MM-DD` y aplican sobre la fecha de vencimiento del payable
        asociado.


        Para obtener el detalle completo de un pago (incluyendo datos de
        contacto del beneficiario, centro de costo, proyectos e información del
        ERP) usá `GET /payments/{reference}`.
      parameters:
        - name: search
          in: query
          description: Búsqueda libre (beneficiario, concepto, etc.).
          schema:
            type: string
            maxLength: 50
        - name: beneficiary_reference
          in: query
          description: >-
            Referencia (UUID) del beneficiario. Acepta múltiples valores
            separados por coma.
          schema:
            type: string
        - name: document_reference
          in: query
          description: >-
            Referencia (UUID) del documento asociado. Acepta múltiples valores
            separados por coma.
          schema:
            type: string
        - name: batch_reference
          in: query
          description: >-
            Referencia (UUID) del lote de pagos. Acepta múltiples valores
            separados por coma.
          schema:
            type: string
        - name: payable_reference
          in: query
          description: Referencia (UUID) del payable asociado.
          schema:
            type: string
        - name: state
          in: query
          description: >-
            Estado de archivado del pago. Si se usa `archived`, el filtro
            `status` se ignora. Por defecto se listan los pagos activos.
          schema:
            type: string
            enum:
              - active
              - archived
        - name: status
          in: query
          description: Filtra por estado del pago.
          schema:
            $ref: '#/components/schemas/PaymentStatus'
        - name: expiration_date_from
          in: query
          description: Fecha de vencimiento desde (inclusive), formato `YYYY-MM-DD`.
          schema:
            type: string
            format: date
        - name: expiration_date_to
          in: query
          description: Fecha de vencimiento hasta (inclusive), formato `YYYY-MM-DD`.
          schema:
            type: string
            format: date
        - name: tags
          in: query
          description: IDs de etiquetas separados por coma (ej. `1,2,3`).
          schema:
            type: string
        - name: payment_method
          in: query
          description: >-
            Métodos de pago separados por coma (ej.
            `card,banking_correspondent`).
          schema:
            type: string
        - name: only_expenses
          in: query
          description: Si es `true`, devuelve únicamente pagos de gastos.
          schema:
            type: boolean
        - name: page
          in: query
          description: Página (1-indexed).
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: page_size
          in: query
          description: Cantidad de ítems por página.
          schema:
            type: integer
            minimum: 1
            default: 25
        - name: sort_by
          in: query
          description: Campo de ordenamiento.
          schema:
            type: string
            enum:
              - created_at
              - amount
              - expiration_date
              - paid_at
              - beneficiary
            default: created_at
        - name: sort_order
          in: query
          description: Dirección de ordenamiento.
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
      responses:
        '200':
          description: Payments list response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentListResponse'
              example:
                items:
                  - reference: aaea7db4-647c-4d92-9f86-89e34a68e1aa
                    beneficiary:
                      reference: 616263a5-a677-4ad1-92ca-7e120adad8d4
                      name: 0411test STG
                      identifier_type: NIT
                      identifier_number: '1100'
                      is_deleted: false
                      deleted_at: null
                      contact_information: []
                    email: null
                    document:
                      reference: b2c3d4e5-f6a7-4890-b123-c456d7890abc
                      type: invoice
                      document_number: FC-2024-001
                      fiscal_reference: >-
                        e19d3e7867371a12fd53b67a56db087faa871c9797993d9bbf7806ae4e1466ea
                      origin: fiscal_entity
                      amount: 10000
                      amount_currency: COP
                      is_canceled: false
                    amount: 10000
                    amount_currency: COP
                    exchange_amount: 10000
                    exchange_currency: null
                    exchange_rate: null
                    status: pending
                    file_path: null
                    receipt_file_path: null
                    is_archived: false
                    payable:
                      reference: a1cde862-db4f-427f-bd95-91a2f8dd06a1
                      type: supplier
                      status: pending
                      amount: 10000
                      amount_currency: COP
                      file_path: null
                      balance: null
                      issue_date: '2025-11-27'
                      expiration_date: '2025-11-28'
                      concept: Factura FC-2024-001
                      origin: fiscal_entity
                      projects: []
                    batch: null
                    tags: []
                    accounting_receipt: null
                    source_of_fund: null
                    paid_at: null
                    payment_method: null
                    created_at: '2025-11-27T16:04:55.400+00:00'
                    updated_at: '2025-11-27T16:04:55.400+00:00'
                total: 1
                current_page: 1
                page_size: 30
                total_pages: 1
        '400':
          description: Bad request / validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    PaymentStatus:
      type: string
      enum:
        - pending
        - in_process
        - processed
        - failed
      description: >-
        Estado del pago: `pending` (creado, sin procesar), `in_process` (en
        procesamiento), `processed` (acreditado) o `failed` (rechazado).
    PaymentListResponse:
      type: object
      required:
        - items
        - total
        - current_page
        - page_size
        - total_pages
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Payment'
        total:
          type: integer
        current_page:
          type: integer
        page_size:
          type: integer
        total_pages:
          type: integer
    ErrorResponse:
      type: object
      required:
        - success
        - error
      properties:
        success:
          type: boolean
          const: false
        error:
          $ref: '#/components/schemas/ErrorObject'
      example:
        success: false
        error:
          code: VALIDATION_ERROR
          message: The request contains invalid data
          details:
            amount:
              - Amount must be greater than 0
            beneficiary_id:
              - Beneficiary does not exist
    Payment:
      type: object
      properties:
        reference:
          type: string
        beneficiary:
          anyOf:
            - $ref: '#/components/schemas/Beneficiary'
            - type: 'null'
        email:
          type:
            - string
            - 'null'
        document:
          description: >-
            Documento fuente del pago cuando el payable está vinculado a un
            documento (p. ej. factura sincronizada desde la DIAN/SAT). Es `null`
            en pagos manuales o anticipos sin documento asociado.
          anyOf:
            - $ref: '#/components/schemas/PaymentDocument'
            - type: 'null'
        amount:
          type: number
        amount_currency:
          $ref: '#/components/schemas/Currency'
        exchange_amount:
          type:
            - number
            - 'null'
        exchange_currency:
          anyOf:
            - $ref: '#/components/schemas/Currency'
            - type: 'null'
        exchange_rate:
          type:
            - number
            - 'null'
        status:
          $ref: '#/components/schemas/PaymentStatus'
        file_path:
          type:
            - string
            - 'null'
        receipt_file_path:
          type:
            - string
            - 'null'
        is_archived:
          type: boolean
        payable:
          anyOf:
            - $ref: '#/components/schemas/Payable'
            - type: 'null'
        batch:
          type:
            - object
            - 'null'
        tags:
          type: array
          items:
            $ref: '#/components/schemas/PaymentTag'
        source_of_fund:
          type:
            - object
            - 'null'
        accounting_receipt:
          type:
            - object
            - 'null'
        paid_at:
          type:
            - string
            - 'null'
          format: date-time
        payment_method:
          type:
            - string
            - 'null'
        payment_gateway:
          type:
            - string
            - 'null'
        created_at:
          type:
            - string
            - 'null'
          format: date-time
        updated_at:
          type:
            - string
            - 'null'
          format: date-time
    ErrorObject:
      type: object
      required:
        - code
        - message
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode'
        message:
          type: string
        details:
          anyOf:
            - $ref: '#/components/schemas/ErrorDetails'
            - type: 'null'
    Beneficiary:
      type: object
      required:
        - reference
        - name
        - identifier_number
      properties:
        reference:
          type: string
        name:
          type: string
        type:
          $ref: '#/components/schemas/BeneficiaryType'
        email:
          type:
            - string
            - 'null'
        phone_number:
          type:
            - string
            - 'null'
        identifier_type:
          anyOf:
            - $ref: '#/components/schemas/IdentifierType'
            - type: 'null'
        identifier_number:
          type: string
        payment_terms:
          type:
            - integer
            - 'null'
        fiscal_address:
          anyOf:
            - type: object
              properties:
                city_code:
                  type:
                    - string
                    - 'null'
                city_name:
                  type:
                    - string
                    - 'null'
                state_code:
                  type:
                    - string
                    - 'null'
                state_name:
                  type:
                    - string
                    - 'null'
            - type: 'null'
        contact_information:
          type: array
          items:
            $ref: '#/components/schemas/ContactInformation'
        bank_accounts:
          type: array
          items:
            $ref: '#/components/schemas/BankAccount'
        created_at:
          type:
            - string
            - 'null'
          format: date-time
        updated_at:
          type:
            - string
            - 'null'
          format: date-time
    PaymentDocument:
      type: object
      description: Resumen del documento asociado al pago a través del payable.
      properties:
        reference:
          type: string
          format: uuid
          description: Referencia interna del documento en Payana.
        type:
          type: string
          description: Tipo de documento (p. ej. `invoice`, `credit_note`).
        document_number:
          type: string
          description: Número de documento visible (p. ej. número de factura).
        fiscal_reference:
          type:
            - string
            - 'null'
          description: >-
            Referencia fiscal del documento (CUFE en Colombia, UUID del CFDI en
            México).
        origin:
          type:
            - string
            - 'null'
          description: Origen del documento (p. ej. `fiscal_entity`, `manual`, `api`).
        amount:
          type: number
          description: Monto total del documento.
        amount_currency:
          $ref: '#/components/schemas/Currency'
        is_canceled:
          type: boolean
          description: Indica si el documento fue cancelado ante el SAT/DIAN.
    Currency:
      type: string
      enum:
        - USD
        - COP
        - MXN
        - EUR
    Payable:
      type: object
      properties:
        reference:
          type: string
        type:
          type: string
        status:
          $ref: '#/components/schemas/PayableStatus'
        amount:
          type: number
        amount_currency:
          $ref: '#/components/schemas/Currency'
        file_path:
          type:
            - string
            - 'null'
        balance:
          type:
            - number
            - 'null'
        issue_date:
          type:
            - string
            - 'null'
          format: date
        expiration_date:
          type:
            - string
            - 'null'
          format: date
        concept:
          type:
            - string
            - 'null'
        origin:
          anyOf:
            - $ref: '#/components/schemas/PayableOrigin'
            - type: 'null'
        projects:
          type: array
          items: {}
    PaymentTag:
      type: object
      description: Etiqueta de un pago.
      properties:
        name:
          type: string
    ErrorCode:
      type: string
      enum:
        - VALIDATION_ERROR
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
        - CONFLICT
        - RATE_LIMITED
        - INTERNAL_ERROR
    ErrorDetails:
      type: object
      additionalProperties:
        type: array
        items:
          type: string
    BeneficiaryType:
      type: string
      enum:
        - supplier
    IdentifierType:
      type: string
      description: Tipo de identificación (ej. NIT, CC, RFC).
    ContactInformation:
      type: object
      required:
        - type
        - value
      properties:
        reference:
          type: string
          description: Referencia del contacto (cuando aplica).
        type:
          type: string
          description: Tipo de contacto (ej. email, phone).
        value:
          type: string
    BankAccount:
      type: object
      required:
        - reference
        - bank_reference
        - bank_name
        - account_number
      properties:
        reference:
          type: string
        bank_reference:
          type: string
          description: Referencia del banco (UUID).
        bank_name:
          type:
            - string
            - 'null'
        account_number:
          type: string
        account_type:
          type: string
          enum:
            - savings
            - checking
        validation_status:
          type: string
          enum:
            - pending
            - processing
            - validated
            - rejected
            - validation_error
        account_recipient_name:
          type:
            - string
            - 'null'
        account_recipient_document_number:
          type:
            - string
            - 'null'
        account_recipient_document_type:
          anyOf:
            - $ref: '#/components/schemas/IdentifierType'
            - type: 'null'
        created_at:
          type:
            - string
            - 'null'
          format: date-time
        updated_at:
          type:
            - string
            - 'null'
          format: date-time
    PayableStatus:
      type: string
      enum:
        - pending
        - paid
      description: 'Estado del payable: `pending` (saldo pendiente) o `paid` (saldado).'
    PayableOrigin:
      type: string
      enum:
        - document
        - manual
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: api-key
      description: API key provista por Payana.

````