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

# Listar tarjetas inscritas

> Retorna las tarjetas activas inscritas que el destinatario (master entity actuando como `client`) puede cobrar. Hoy solo se exponen tarjetas vía Transbank OneClick.

## ¿Para qué se usa?

Obtiene las tarjetas activas inscritas que un destinatario (master entity) puede cobrar. Útil para mostrar al destinatario qué pagadores tienen tarjeta inscrita y poder ofrecerles cobros recurrentes o cobros directos sin redirigir al checkout cada vez.

## Qué hace

* Retorna las tarjetas con `is_active=True` cuya master entity de cobro coincide con `master_entity_id`.
* Por cada tarjeta incluye los datos del pagador (RUT, nombre), los últimos 4 dígitos, la marca, el vencimiento y el proveedor.
* Hoy solo se exponen tarjetas vía **Transbank OneClick**.

## Consideraciones importantes

### Scope por API Key

La API Key debe pertenecer a un usuario con acceso a la master entity indicada en la URL. Si no, el endpoint responde `403`.

### Tarjetas inactivas

Una tarjeta puede quedar inactiva si el pagador la dio de baja, si Transbank rechazó el OneClick o si se reemplazó por otra del mismo pagador (solo un método activo por pagador para esa master entity). El endpoint no las retorna.

<Info>
  Hoy las tarjetas se inscriben desde el frontend de Tupana (no hay endpoint público de inscripción). Este endpoint te sirve para consultar el estado actual.
</Info>


## OpenAPI

````yaml api-reference/openapi-payment-requests.json GET /master-entities/{master_entity_id}/payment-methods/
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:
  /master-entities/{master_entity_id}/payment-methods/:
    get:
      tags:
        - Medios de pago
      summary: Listar tarjetas inscritas
      description: >-
        Retorna las tarjetas activas inscritas que el destinatario (master
        entity actuando como `client`) puede cobrar. Hoy solo se exponen
        tarjetas vía Transbank OneClick.
      operationId: listPaymentMethods
      parameters:
        - name: master_entity_id
          in: path
          required: true
          description: ID del destinatario (MasterEntity) que cobra con estas tarjetas.
          schema:
            type: integer
      responses:
        '200':
          description: Lista de tarjetas inscritas (puede ser vacía)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentMethodListResponse'
              example:
                results:
                  - payment_method_id: 814
                    type: card
                    is_default: true
                    email: juan@ejemplo.com
                    card_last4: '6623'
                    card_type: Visa
                    card_expiration: 12/2030
                    provider: transbank_oneclick
                    payer:
                      id: 482
                      tax_id: 11.111.111-1
                      name: Juan Soto
                    created_at: '2026-04-06T12:00:00Z'
        '401':
          description: API key inválida o no proporcionada
        '403':
          description: La API key no pertenece a un usuario con acceso a este destinatario
        '404':
          description: Destinatario no encontrado
      security:
        - apiKeyAuth: []
components:
  schemas:
    PaymentMethodListResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/PaymentMethodResponse'
    PaymentMethodResponse:
      type: object
      properties:
        payment_method_id:
          type: integer
          description: ID único del medio de pago.
          example: 814
        type:
          type: string
          enum:
            - card
            - bank_account
            - other
          description: Tipo del medio de pago. Hoy el endpoint solo retorna `card`.
          example: card
        is_default:
          type: boolean
          description: Si es el medio de pago marcado como por defecto para ese pagador.
          example: true
        email:
          type: string
          description: Email asociado a la inscripción (puede venir vacío).
          example: juan@ejemplo.com
        card_last4:
          type: string
          description: Últimos 4 dígitos de la tarjeta (vacío si no es tarjeta).
          example: '6623'
        card_type:
          type: string
          description: Marca de la tarjeta (Visa, Mastercard, etc).
          example: Visa
        card_expiration:
          type: string
          description: Vencimiento de la tarjeta en formato `MM/YYYY`.
          example: 12/2030
        provider:
          type: string
          enum:
            - transbank_oneclick
            - ''
          description: Proveedor que opera la inscripción.
          example: transbank_oneclick
        payer:
          $ref: '#/components/schemas/PaymentMethodPayer'
        created_at:
          type: string
          format: date-time
          description: Fecha en que se inscribió el medio de pago.
          example: '2026-04-06T12:00:00Z'
    PaymentMethodPayer:
      type: object
      description: Pagador (dueño de la tarjeta).
      properties:
        id:
          type: integer
          example: 482
        tax_id:
          type: string
          example: 11.111.111-1
        name:
          type: string
          example: Juan Soto
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'API Key para autenticación. Formato: `Api-Key YOUR-API-KEY`'

````