v1

latestOpenAPI 3.1.02026-07-228956435.8 KB

Invoices

Create an invoice

Creates a one-off invoice for a customer, in the live or test mode of the API key used. The invoice is not tied to a subscription and starts in draft status. Fintoc does not charge the invoice until you finalize it. The total is the sum of the lines, which must all share the same currency. Fintoc charges the invoice automatically against default_payment_method, so collection_method is always charge_automatically.

post/invoices

Request body

customerstring required

ID of the customer the invoice bills.

default_payment_methodstring required

Payment method Fintoc charges when the invoice is finalized. Must belong to the specified customer.

collection_method'charge_automatically'

How Fintoc collects the invoice. Only charge_automatically is supported. Defaults to charge_automatically.

metadataobject

Set of key-value pairs you can attach to the invoice.

Example request

{
  "customer": "cus_2c4mDe9NJyGmMzvCqLkXqAtjnRu",
  "default_payment_method": "pm_2c4mDhAbCdEfGhIjKlMnOpQrStu",
  "lines": [
    {
      "amount": 60000,
      "currency": "CLP",
      "name": "Design",
      "description": "Design work",
      "quantity": 1
    }
  ],
  "collection_method": "charge_automatically",
  "metadata": {
    "order_id": "12345"
  }
}

Response

The created invoice, in draft status.

idstring required

Unique identifier of the invoice.

hosted_invoice_urlstring nullable required

URL of the hosted invoice page, where your customer can view and pay the invoice. null for test mode invoices and for invoices that are not open.

object'invoice' required

Type of the object. Always invoice.

attempt_countinteger required

Number of automatic charge attempts Fintoc has made on the invoice. 0 until the invoice is finalized and charged for the first time.

created_atstring date-time required

ISO 8601 timestamp of when the invoice was created.

currency'CLP' | 'MXN' required

Currency of the invoice, as an ISO 4217 code. Every line item uses this currency.

customerstring required

id of the customer the invoice bills.

default_payment_methodstring nullable required

id of the payment method Fintoc charges when the invoice is finalized. null for invoices without one, such as subscription invoices.

metadataobject nullable required

Set of key-value pairs attached to the invoice. null when the invoice has no metadata.

mode'live' | 'test' required

Mode of the invoice. live invoices use real data; test invoices use fake data for integration testing. An API key only sees invoices that share its mode.

next_payment_attempt_atstring date-time nullable required

ISO 8601 timestamp of the next scheduled automatic charge attempt. null when no further attempt is scheduled.

status'draft' | 'open' | 'paid' | 'void' required

Status of the invoice. Invoices start as draft, become open when finalized, and end as paid or void.

subscriptionstring nullable required

id of the subscription that generated the invoice. null for invoices not tied to a subscription.

totalinteger required

Total amount of the invoice, in the smallest unit of currency (for example, 30000 for $30000 CLP, since CLP has no minor unit, or 3000 for $30.00 MXN). Equals the sum of the line item amounts.

Example response

{
  "id": "inv_2bVdWxLpzXq8RkNcM3JtUv9AhTe",
  "hosted_invoice_url": "https://acme.billing.fintoc.com/invoices/inv_2bVdWxLpzXq8RkNcM3JtUv9AhTe",
  "attempt_count": 1,
  "created_at": "2026-05-01T12:00:00Z",
  "currency": "CLP",
  "customer": "cus_2bVdWyTnGq4PfLs7DkXjRm0CwIo",
  "default_payment_method": "pm_2c4mDhAbCdEfGhIjKlMnOpQrStu",
  "lines": [
    {
      "id": "il_2bVdX0PqJs6RhNu9FmZlTo2EyKq",
      "amount": 30000,
      "currency": "CLP",
      "description": "A premium plan",
      "name": "Premium Plan",
      "period_end": "2026-06-01T00:00:00Z",
      "period_start": "2026-05-01T00:00:00Z",
      "quantity": 1
    }
  ],
  "mode": "live",
  "next_payment_attempt_at": "2026-05-02T12:00:00Z",
  "payments": [
    {
      "amount": 30000,
      "currency": "CLP",
      "payment_intent": "pi_2bVdX2RsLu8TjPwBHoBnVq4G0Ms",
      "status": "succeeded"
    }
  ],
  "status": "draft",
  "subscription": "sub_2bVdWzKfHr5QgMt8ElYkSn1DxJp",
  "total": 30000
}