Gestionar invoices

Cuando creas una suscripción, 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.

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:

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.

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.

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.

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.

Servidor

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"
    }
  }'

Node

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'
  }
});

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

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

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:

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.
Cobrar la invoice a pedido con Pagar una invoice, usando el payment method asociado a la suscripción.
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. 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 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.

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

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
      }
    ]
  }'

Node

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
    }
  ]
});

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:

{
  "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 antes de que la invoice salga de draft.

​Invoices en el flujo de suscripción

​Recuperar un pago fallido

​Cobra un monto fuera del ciclo de facturación

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

​Probar la creación de invoice con estado draft

Invoices en el flujo de suscripción

Recuperar un pago fallido

Cobra un monto fuera del ciclo de facturación

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

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