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

# Gestionar invoices

> Maneja las invoices que una suscripción de Fintoc emite en cada ciclo de facturación, recupera un cobro fallido y crea tus propias invoices por montos fuera del ciclo.

Cuando creas una [suscripción](/es/guides/payments/accept-recurring-payments), Fintoc genera un `Invoice` por cada ciclo de facturación. Una invoice representa el monto que tu cliente debe por un período dado. Con `charge_automatically`, Fintoc intenta cobrar la invoice usando el método de pago inscrito. Con `send_invoice`, la invoice queda `open` para que la cobres tú.

Fintoc crea las invoices de la suscripción por ti. También puedes crear tus propias invoices por montos que la suscripción no cubre, y cobrar cualquier invoice abierta bajo demanda.

Para detalles completos sobre invoices, consulta el [Invoice object](/es/api/payments-api/invoices/invoice-object).

## Invoices en el flujo de suscripción

Después del evento `checkout_session.finished`, Fintoc crea la primera invoice y cobra el método de pago inscrito. Con `charge_automatically`, la suscripción queda `incomplete` hasta que ese primer pago tiene éxito, y ahí pasa a `active`. Maneja los siguientes eventos relacionados a invoices junto con los eventos posteriores a la sesión en [Crea suscripciones para tu cliente](/es/guides/payments/accept-recurring-payments#maneja-los-eventos-posteriores-a-la-sesión):

| Evento                      | Descripción                                                                                                                           | Acción                                                                                                      |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `invoice.created`           | Enviado cuando Fintoc genera una nueva invoice para un ciclo de facturación.                                                          | Registra la invoice y actualiza tus registros.                                                              |
| `invoice.finalized`         | Enviado cuando Fintoc finaliza la invoice y queda lista para el pago.                                                                 | Guarda el `hosted_invoice_url`, pero envíaselo a tu cliente solo si el cobro automático falla más adelante. |
| `invoice.payment_created`   | Enviado cuando comienza un pago de la invoice, ya sea desde un cobro automático o desde tu cliente usando el `hosted_invoice_url`.    | Trata el evento como informativo. No envíes el `hosted_invoice_url` mientras un pago está en curso.         |
| `invoice.payment_succeeded` | Enviado cuando Fintoc cobra el pago de la invoice.                                                                                    | Confirma el pago a tu cliente y extiende el acceso.                                                         |
| `invoice.paid`              | Enviado en toda transición a `paid`, ya sea que Fintoc haya cobrado la invoice o que tú la hayas marcado como pagada fuera de Fintoc. | Salda la deuda en tus registros. Lee `external_payment` para saber si la plata pasó por Fintoc.             |
| `invoice.payment_failed`    | Enviado cuando un intento de pago para la invoice falla.                                                                              | Envía el `hosted_invoice_url` para que tu cliente pueda pagar la invoice.                                   |
| `invoice.voided`            | Enviado cuando una invoice se anula y Fintoc deshabilita su `hosted_invoice_url`.                                                     | Actualiza tus registros.                                                                                    |

**Mes 1:** Cuando se crea la suscripción, Fintoc genera la primera invoice y la finaliza sin la ventana de una hora en `draft`. Luego Fintoc cobra el método de pago inscrito. En caso de éxito, recibes `invoice.created`, seguido de `invoice.finalized`, `invoice.payment_succeeded`, `invoice.paid` y `payment_intent.succeeded`.

**Mes 2 en adelante:** En cada renovación de ciclo de facturación, según el `billing_cycle_anchor` de la suscripción, Fintoc crea una nueva invoice en estado `draft`. Después de 1 hora, Fintoc finaliza la invoice, la pasa a `open` y cobra el método de pago inscrito. Usa esa hora para ajustar la invoice antes de que Fintoc la cobre. En caso de éxito, recibes `invoice.finalized`, `invoice.payment_succeeded` e `invoice.paid`. En caso de falla, recibes `invoice.payment_failed`.

Fintoc finaliza las invoices de una suscripción por ti. Una invoice que creas tú queda en `draft` hasta que la finalices, como se describe en [Cobra un monto fuera del ciclo de facturación](#cobra-un-monto-fuera-del-ciclo-de-facturación).

## Recuperar un pago fallido

Cuando un cobro automático falla, Fintoc emite `invoice.payment_failed`. Para recuperar el pago, envía el `hosted_invoice_url` de la invoice a tu cliente por tu propio canal, como email o WhatsApp. La página alojada permite que tu cliente pague usando los métodos de pago habilitados en la cuenta de tu organización. Un pago exitoso crea un `payment_intent` en la invoice y salda la deuda. El método de pago inscrito de la suscripción sigue siendo válido, y Fintoc cobra el siguiente ciclo automáticamente.

El `hosted_invoice_url` queda disponible en el objeto `Invoice` una vez que la invoice alcanza el estado `open`. Para más detalles, consulta el [Invoice object](/es/api/payments-api/invoices/invoice-object).

<Info>
  Una invoice acepta solo un pago a la vez. Si abres el `hosted_invoice_url` mientras un cobro automático está en curso, la página muestra que hay un pago de invoice en progreso y el enlace de pago queda deshabilitado. Fintoc vuelve a habilitar el enlace de pago si el cobro automático falla.
</Info>

## Cobra un monto fuera del ciclo de facturación

Fintoc emite las invoices de la suscripción por ti. También puedes crear una invoice tú mismo por un monto que la suscripción no cubre. Úsala para un ajuste puntual, un servicio extra o un cobro fuera del calendario de facturación. Créala para el mismo `customer`, con el método de pago inscrito durante el checkout como `default_payment_method`.

<Frame>
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/fintoc-49b8bee8/images/invoice-flow-diagram.png" alt="fintoc-invoice-creation-diagram" />
</Frame>

**Servidor**

```bash theme={null}
curl --request POST "https://api.fintoc.com/v2/invoices" \
  --header "Authorization: YOUR_SECRET_API_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '{
    "customer": "cus_NffrFeUfNV2Hib",
    "default_payment_method": "pm_NffrFeUfNV2Hib",
    "collection_method": "charge_automatically",
    "lines": [
      {
        "name": "Plan upgrade",
        "amount": 50000,
        "currency": "CLP",
        "quantity": 1
      }
    ],
    "metadata": {
      "order_id": "order_98765"
    }
  }'
```

```javascript Node theme={null}
const { Fintoc } = require('fintoc');

const fintoc = new Fintoc('YOUR_SECRET_API_KEY');

const invoice = await fintoc.v2.invoices.create({
  customer: 'cus_NffrFeUfNV2Hib',
  default_payment_method: 'pm_NffrFeUfNV2Hib',
  collection_method: 'charge_automatically',
  lines: [
    {
      name: 'Plan upgrade',
      amount: 50000,
      currency: 'CLP',
      quantity: 1
    }
  ],
  metadata: {
    order_id: 'order_98765'
  }
});
```

```python theme={null}
from fintoc import Fintoc

client = Fintoc('YOUR_SECRET_API_KEY')

invoice = client.v2.invoices.create(
    customer='cus_NffrFeUfNV2Hib',
    default_payment_method='pm_NffrFeUfNV2Hib',
    collection_method='charge_automatically',
    lines=[
        {
            'name': 'Plan upgrade',
            'amount': 50000,
            'currency': 'CLP',
            'quantity': 1,
        }
    ],
    metadata={
        'order_id': 'order_98765'
    }
)
```

Fintoc devuelve la invoice en estado `draft`, con `subscription` en `null`. La invoice le cobra al customer, no a la suscripción, así que no cambia el ciclo de facturación ni el monto de la suscripción. [Finaliza la invoice](/es/api/payments-api/invoices/invoices-finalize) para pasarla a `open` y cobrar el `default_payment_method`. A diferencia de las invoices de una suscripción, que Fintoc finaliza por su cuenta después de una hora en `draft`, una invoice que creas tú queda en `draft` hasta que la finalices.

**Servidor**

```bash theme={null}
curl --request POST "https://api.fintoc.com/v2/invoices/inv_2bVdWxLpzXq8RkNcM3JtUv9AhTe/finalize" \
  --header "Authorization: YOUR_SECRET_API_KEY"
```

Después de finalizarla, la invoice se comporta como una invoice de suscripción. Emite los mismos eventos `invoice.*`, guarda el mismo historial en `payments` y expone el mismo `hosted_invoice_url` como respaldo cuando un cobro falla. También puedes reintentar un cobro fallido con [Pagar una invoice](/es/api/payments-api/invoices/invoices-pay), contra el método de pago inscrito o contra otro método activo del mismo customer.

Para el flujo on-demand completo, incluyendo cómo cobrar una invoice a un cliente sin método de pago inscrito, consulta [Guardar un método de pago para cobros futuros](/es/guides/payments/accept-recurring-payments/setup-a-payment-method-for-future-charges).

## Cobrar las invoices tú mismo en vez de cobrar automáticamente

Con `collection_method` en `send_invoice`, Fintoc deja de hacer cobros automáticos. Fintoc igual emite una invoice por período de facturación, pero cada invoice queda `open` y tú decides cómo cobrarla. Tienes tres formas de saldar una invoice abierta:

1. Enviarle a tu cliente el link de pago que está en `hosted_invoice_url` y dejar que pague en la página alojada por Fintoc.
2. Cobrar la invoice a pedido con [Pagar una invoice](/es/api/payments-api/invoices/invoices-pay), usando el payment method asociado a la suscripción.
3. Cobrar la plata fuera de Fintoc, por transferencia o en efectivo, y marcar la invoice como pagada. Fintoc lo registra con `external_payment` en `true`.

Como `send_invoice` nunca cobra automáticamente, no requiere payment method. Para crear una suscripción así con la API, sin pasar a tu cliente por un enrolamiento de checkout, consulta [Emite invoices sin cobrar](/es/guides/payments/accept-recurring-payments#emite-invoices-sin-cobrar). Igual puedes asociar un payment method después, lo que te permite cobrar invoices a pedido.

Fintoc no contacta a tu cliente por ningún canal. Contactarlo es tu responsabilidad, cualquiera sea la opción que uses.

Cobrar las invoices tú mismo tiene tres consecuencias:

* Las invoices impagas se acumulan. Cada período de facturación agrega una invoice, y cada una se salda por separado.
* La suscripción nace `active`, y eso no significa que tu cliente haya pagado. Con `send_invoice` no hay cobro que esperar, así que Fintoc se salta el estado `incomplete` que usa con `charge_automatically`. Sigue el `status` de cada invoice para saber qué te debe tu cliente.
* Solo [Actualizar una suscripción](/es/api/payments-api/subscriptions/subscriptions-update) cambia el modo de cobro. Asociar un payment method no cambia la suscripción a `charge_automatically`.

Los eventos son distintos según quién cobra. Consulta [Eventos de pago de una invoice](/es/api/main-resources/events-reference/types-of-events#eventos-de-pago-de-una-invoice).

## Probar la creación de invoice con estado `draft`

Para probar una invoice que se crea en estado `draft`, crea una suscripción con un line item usando el nombre de producto `sandbox_draft`:

**Servidor**

```bash theme={null}
curl --request POST "https://api.fintoc.com/v2/checkout_sessions" \
  --header "Authorization: YOUR_TEST_SECRET_API_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '{
    "flow": "subscription",
    "amount": 350000,
    "currency": "CLP",
    "success_url": "https://merchant.com/success",
    "cancel_url": "https://merchant.com/cancel",
    "payment_method_types": ["pac"],
    "customer_data": {
      "tax_id": {
        "type": "cl_rut",
        "value": "11.111.111-1"
      },
      "name": "Felipe Castro",
      "email": "jon@snow.com"
    },
    "line_items": [
      {
        "price_data": {
          "currency": "CLP",
          "unit_amount": 350000,
          "product_data": {
            "name": "sandbox_draft"
          },
          "recurring": {
            "interval": "month",
            "interval_count": 1
          }
        },
        "quantity": 1
      }
    ]
  }'
```

```javascript Node theme={null}
const { Fintoc } = require('fintoc');

const fintoc = new Fintoc('YOUR_TEST_SECRET_API_KEY');

const checkoutSession = await fintoc.v2.checkoutSessions.create({
  flow: 'subscription',
  amount: 350000,
  currency: 'CLP',
  success_url: 'https://merchant.com/success',
  cancel_url: 'https://merchant.com/cancel',
  payment_method_types: ['pac'],
  customer_data: {
    tax_id: {
      type: 'cl_rut',
      value: '11.111.111-1'
    },
    name: 'Felipe Castro',
    email: 'jon@snow.com'
  },
  line_items: [
    {
      price_data: {
        currency: 'CLP',
        unit_amount: 350000,
        product_data: {
          name: 'sandbox_draft'
        },
        recurring: {
          interval: 'month',
          interval_count: 1
        }
      },
      quantity: 1
    }
  ]
});
```

```python theme={null}
from fintoc import Fintoc

client = Fintoc('YOUR_TEST_SECRET_API_KEY')

checkout_session = client.v2.checkout_sessions.create(
    flow='subscription',
    amount=350000,
    currency='CLP',
    success_url='https://merchant.com/success',
    cancel_url='https://merchant.com/cancel',
    payment_method_types=['pac'],
    customer_data={
        'tax_id': {
            'type': 'cl_rut',
            'value': '11.111.111-1',
        },
        'name': 'Felipe Castro',
        'email': 'jon@snow.com',
    },
    line_items=[
        {
            'price_data': {
                'currency': 'CLP',
                'unit_amount': 350000,
                'product_data': {
                    'name': 'sandbox_draft',
                },
                'recurring': {
                    'interval': 'month',
                    'interval_count': 1,
                },
            },
            'quantity': 1,
        }
    ],
)
```

Fintoc crea el `Checkout Session`:

```json theme={null}
{
  "id": "cs_li5531onlFDi235",
  "object": "checkout_session",
  "mode": "test",
  "flow": "subscription",
  "status": "created",
  "amount": 350000,
  "currency": "CLP",
  "payment_method_types": ["pac"],
  "customer": {
    "id": "cus_NffrFeUfNV2Hib",
    "object": "customer",
    "name": "Felipe Castro",
    "email": "jon@snow.com",
    "metadata": {},
    "tax_id": {
      "type": "cl_rut",
      "value": "11.111.111-1"
    }
  },
  "line_items": [
    {
      "price": {
        "product": {
          "name": "sandbox_draft",
          "description": "Fixed-amount monthly plan"
        },
        "currency": "CLP",
        "unit_amount": 350000,
        "recurring": {
          "interval": "month",
          "interval_count": 1
        }
      },
      "quantity": 1
    }
  ],
  "success_url": "https://merchant.com/success",
  "cancel_url": "https://merchant.com/cancel",
  "redirect_url": "https://pay.fintoc.com/checkout/cs_li5531onlFDi235"
}
```

Fintoc crea la invoice en estado `draft`, de modo que puedas editar sus ítems con el endpoint [Add lines](/es/api/payments-api/invoices/invoices-add-lines) antes de que la invoice salga de `draft`.