Create an invoice

curl --request POST \
  --url https://api.fintoc.com/v2/invoices \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer": "cus_2c4mDe9NJyGmMzvCqLkXqAtjnRu",
  "lines": [
    {
      "amount": 60000,
      "currency": "CLP",
      "name": "Design",
      "quantity": 1,
      "description": "Design work"
    }
  ],
  "default_payment_method": "pm_2c4mDhAbCdEfGhIjKlMnOpQrStu",
  "collection_method": "send_invoice",
  "metadata": {
    "order_id": "12345"
  },
  "business_profile": {
    "category": "541100",
    "name": "Test Business",
    "tax_id": "11.111.111-1"
  }
}
'

import requests

url = "https://api.fintoc.com/v2/invoices"

payload = {
    "customer": "cus_2c4mDe9NJyGmMzvCqLkXqAtjnRu",
    "lines": [
        {
            "amount": 60000,
            "currency": "CLP",
            "name": "Design",
            "quantity": 1,
            "description": "Design work"
        }
    ],
    "default_payment_method": "pm_2c4mDhAbCdEfGhIjKlMnOpQrStu",
    "collection_method": "send_invoice",
    "metadata": { "order_id": "12345" },
    "business_profile": {
        "category": "541100",
        "name": "Test Business",
        "tax_id": "11.111.111-1"
    }
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    customer: 'cus_2c4mDe9NJyGmMzvCqLkXqAtjnRu',
    lines: [
      {
        amount: 60000,
        currency: 'CLP',
        name: 'Design',
        quantity: 1,
        description: 'Design work'
      }
    ],
    default_payment_method: 'pm_2c4mDhAbCdEfGhIjKlMnOpQrStu',
    collection_method: 'send_invoice',
    metadata: {order_id: '12345'},
    business_profile: {category: '541100', name: 'Test Business', tax_id: '11.111.111-1'}
  })
};

fetch('https://api.fintoc.com/v2/invoices', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.fintoc.com/v2/invoices",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'customer' => 'cus_2c4mDe9NJyGmMzvCqLkXqAtjnRu',
    'lines' => [
        [
                'amount' => 60000,
                'currency' => 'CLP',
                'name' => 'Design',
                'quantity' => 1,
                'description' => 'Design work'
        ]
    ],
    'default_payment_method' => 'pm_2c4mDhAbCdEfGhIjKlMnOpQrStu',
    'collection_method' => 'send_invoice',
    'metadata' => [
        'order_id' => '12345'
    ],
    'business_profile' => [
        'category' => '541100',
        'name' => 'Test Business',
        'tax_id' => '11.111.111-1'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.fintoc.com/v2/invoices"

	payload := strings.NewReader("{\n  \"customer\": \"cus_2c4mDe9NJyGmMzvCqLkXqAtjnRu\",\n  \"lines\": [\n    {\n      \"amount\": 60000,\n      \"currency\": \"CLP\",\n      \"name\": \"Design\",\n      \"quantity\": 1,\n      \"description\": \"Design work\"\n    }\n  ],\n  \"default_payment_method\": \"pm_2c4mDhAbCdEfGhIjKlMnOpQrStu\",\n  \"collection_method\": \"send_invoice\",\n  \"metadata\": {\n    \"order_id\": \"12345\"\n  },\n  \"business_profile\": {\n    \"category\": \"541100\",\n    \"name\": \"Test Business\",\n    \"tax_id\": \"11.111.111-1\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.fintoc.com/v2/invoices")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"customer\": \"cus_2c4mDe9NJyGmMzvCqLkXqAtjnRu\",\n  \"lines\": [\n    {\n      \"amount\": 60000,\n      \"currency\": \"CLP\",\n      \"name\": \"Design\",\n      \"quantity\": 1,\n      \"description\": \"Design work\"\n    }\n  ],\n  \"default_payment_method\": \"pm_2c4mDhAbCdEfGhIjKlMnOpQrStu\",\n  \"collection_method\": \"send_invoice\",\n  \"metadata\": {\n    \"order_id\": \"12345\"\n  },\n  \"business_profile\": {\n    \"category\": \"541100\",\n    \"name\": \"Test Business\",\n    \"tax_id\": \"11.111.111-1\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.fintoc.com/v2/invoices")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"customer\": \"cus_2c4mDe9NJyGmMzvCqLkXqAtjnRu\",\n  \"lines\": [\n    {\n      \"amount\": 60000,\n      \"currency\": \"CLP\",\n      \"name\": \"Design\",\n      \"quantity\": 1,\n      \"description\": \"Design work\"\n    }\n  ],\n  \"default_payment_method\": \"pm_2c4mDhAbCdEfGhIjKlMnOpQrStu\",\n  \"collection_method\": \"send_invoice\",\n  \"metadata\": {\n    \"order_id\": \"12345\"\n  },\n  \"business_profile\": {\n    \"category\": \"541100\",\n    \"name\": \"Test Business\",\n    \"tax_id\": \"11.111.111-1\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "id": "inv_2bVdWxLpzXq8RkNcM3JtUv9AhTe",
  "object": "invoice",
  "collection_method": "charge_automatically",
  "attempt_count": 0,
  "created_at": "2026-05-01T12:00:00Z",
  "currency": "CLP",
  "customer": "cus_2c4mDe9NJyGmMzvCqLkXqAtjnRu",
  "default_payment_method": "pm_2c4mDhAbCdEfGhIjKlMnOpQrStu",
  "hosted_invoice_url": null,
  "lines": [
    {
      "id": "il_2bVdX0PqJs6RhNu9FmZlTo2EyKq",
      "object": "line_item",
      "name": "Design",
      "description": "Design work",
      "amount": 60000,
      "currency": "CLP",
      "period_end": null,
      "period_start": null,
      "quantity": 2
    },
    {
      "id": "il_2bVdX1QrKt7SiOvAGnAmUp3FzLr",
      "object": "line_item",
      "name": "Hosting",
      "description": "Hosting",
      "amount": 40000,
      "currency": "CLP",
      "period_end": null,
      "period_start": null,
      "quantity": 1
    }
  ],
  "metadata": {
    "order_id": "12345"
  },
  "mode": "live",
  "next_payment_attempt_at": null,
  "payments": [],
  "status": "draft",
  "subscription": null,
  "total": 100000
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_enum",
    "param": "collection_method",
    "message": "Invalid collection_method: wire_transfer. Must be one of 'charge_automatically' or 'send_invoice'.",
    "doc_url": "https://docs.fintoc.com/reference/errors"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "Invalid API Key: invalid-*oken"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_resource",
    "message": "No such payment_method: pm_2c4mDhAbCdEfGhIjKlMnOpQrStu",
    "doc_url": "https://docs.fintoc.com/reference/errors"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "currency_mismatch",
    "message": "The currency is not allowed for the organization's country",
    "doc_url": "https://docs.fintoc.com/reference/errors"
  }
}

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. The collection_method decides how Fintoc collects the invoice once you finalize it. With charge_automatically, the default, Fintoc charges default_payment_method, so the payment method is required. With send_invoice, Fintoc leaves the invoice open for you to collect, and default_payment_method is optional.

POST

invoices

Create an invoice

curl --request POST \
  --url https://api.fintoc.com/v2/invoices \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer": "cus_2c4mDe9NJyGmMzvCqLkXqAtjnRu",
  "lines": [
    {
      "amount": 60000,
      "currency": "CLP",
      "name": "Design",
      "quantity": 1,
      "description": "Design work"
    }
  ],
  "default_payment_method": "pm_2c4mDhAbCdEfGhIjKlMnOpQrStu",
  "collection_method": "send_invoice",
  "metadata": {
    "order_id": "12345"
  },
  "business_profile": {
    "category": "541100",
    "name": "Test Business",
    "tax_id": "11.111.111-1"
  }
}
'

import requests

url = "https://api.fintoc.com/v2/invoices"

payload = {
    "customer": "cus_2c4mDe9NJyGmMzvCqLkXqAtjnRu",
    "lines": [
        {
            "amount": 60000,
            "currency": "CLP",
            "name": "Design",
            "quantity": 1,
            "description": "Design work"
        }
    ],
    "default_payment_method": "pm_2c4mDhAbCdEfGhIjKlMnOpQrStu",
    "collection_method": "send_invoice",
    "metadata": { "order_id": "12345" },
    "business_profile": {
        "category": "541100",
        "name": "Test Business",
        "tax_id": "11.111.111-1"
    }
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    customer: 'cus_2c4mDe9NJyGmMzvCqLkXqAtjnRu',
    lines: [
      {
        amount: 60000,
        currency: 'CLP',
        name: 'Design',
        quantity: 1,
        description: 'Design work'
      }
    ],
    default_payment_method: 'pm_2c4mDhAbCdEfGhIjKlMnOpQrStu',
    collection_method: 'send_invoice',
    metadata: {order_id: '12345'},
    business_profile: {category: '541100', name: 'Test Business', tax_id: '11.111.111-1'}
  })
};

fetch('https://api.fintoc.com/v2/invoices', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.fintoc.com/v2/invoices",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'customer' => 'cus_2c4mDe9NJyGmMzvCqLkXqAtjnRu',
    'lines' => [
        [
                'amount' => 60000,
                'currency' => 'CLP',
                'name' => 'Design',
                'quantity' => 1,
                'description' => 'Design work'
        ]
    ],
    'default_payment_method' => 'pm_2c4mDhAbCdEfGhIjKlMnOpQrStu',
    'collection_method' => 'send_invoice',
    'metadata' => [
        'order_id' => '12345'
    ],
    'business_profile' => [
        'category' => '541100',
        'name' => 'Test Business',
        'tax_id' => '11.111.111-1'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.fintoc.com/v2/invoices"

	payload := strings.NewReader("{\n  \"customer\": \"cus_2c4mDe9NJyGmMzvCqLkXqAtjnRu\",\n  \"lines\": [\n    {\n      \"amount\": 60000,\n      \"currency\": \"CLP\",\n      \"name\": \"Design\",\n      \"quantity\": 1,\n      \"description\": \"Design work\"\n    }\n  ],\n  \"default_payment_method\": \"pm_2c4mDhAbCdEfGhIjKlMnOpQrStu\",\n  \"collection_method\": \"send_invoice\",\n  \"metadata\": {\n    \"order_id\": \"12345\"\n  },\n  \"business_profile\": {\n    \"category\": \"541100\",\n    \"name\": \"Test Business\",\n    \"tax_id\": \"11.111.111-1\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.fintoc.com/v2/invoices")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"customer\": \"cus_2c4mDe9NJyGmMzvCqLkXqAtjnRu\",\n  \"lines\": [\n    {\n      \"amount\": 60000,\n      \"currency\": \"CLP\",\n      \"name\": \"Design\",\n      \"quantity\": 1,\n      \"description\": \"Design work\"\n    }\n  ],\n  \"default_payment_method\": \"pm_2c4mDhAbCdEfGhIjKlMnOpQrStu\",\n  \"collection_method\": \"send_invoice\",\n  \"metadata\": {\n    \"order_id\": \"12345\"\n  },\n  \"business_profile\": {\n    \"category\": \"541100\",\n    \"name\": \"Test Business\",\n    \"tax_id\": \"11.111.111-1\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.fintoc.com/v2/invoices")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"customer\": \"cus_2c4mDe9NJyGmMzvCqLkXqAtjnRu\",\n  \"lines\": [\n    {\n      \"amount\": 60000,\n      \"currency\": \"CLP\",\n      \"name\": \"Design\",\n      \"quantity\": 1,\n      \"description\": \"Design work\"\n    }\n  ],\n  \"default_payment_method\": \"pm_2c4mDhAbCdEfGhIjKlMnOpQrStu\",\n  \"collection_method\": \"send_invoice\",\n  \"metadata\": {\n    \"order_id\": \"12345\"\n  },\n  \"business_profile\": {\n    \"category\": \"541100\",\n    \"name\": \"Test Business\",\n    \"tax_id\": \"11.111.111-1\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "id": "inv_2bVdWxLpzXq8RkNcM3JtUv9AhTe",
  "object": "invoice",
  "collection_method": "charge_automatically",
  "attempt_count": 0,
  "created_at": "2026-05-01T12:00:00Z",
  "currency": "CLP",
  "customer": "cus_2c4mDe9NJyGmMzvCqLkXqAtjnRu",
  "default_payment_method": "pm_2c4mDhAbCdEfGhIjKlMnOpQrStu",
  "hosted_invoice_url": null,
  "lines": [
    {
      "id": "il_2bVdX0PqJs6RhNu9FmZlTo2EyKq",
      "object": "line_item",
      "name": "Design",
      "description": "Design work",
      "amount": 60000,
      "currency": "CLP",
      "period_end": null,
      "period_start": null,
      "quantity": 2
    },
    {
      "id": "il_2bVdX1QrKt7SiOvAGnAmUp3FzLr",
      "object": "line_item",
      "name": "Hosting",
      "description": "Hosting",
      "amount": 40000,
      "currency": "CLP",
      "period_end": null,
      "period_start": null,
      "quantity": 1
    }
  ],
  "metadata": {
    "order_id": "12345"
  },
  "mode": "live",
  "next_payment_attempt_at": null,
  "payments": [],
  "status": "draft",
  "subscription": null,
  "total": 100000
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_enum",
    "param": "collection_method",
    "message": "Invalid collection_method: wire_transfer. Must be one of 'charge_automatically' or 'send_invoice'.",
    "doc_url": "https://docs.fintoc.com/reference/errors"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "Invalid API Key: invalid-*oken"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_resource",
    "message": "No such payment_method: pm_2c4mDhAbCdEfGhIjKlMnOpQrStu",
    "doc_url": "https://docs.fintoc.com/reference/errors"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "currency_mismatch",
    "message": "The currency is not allowed for the organization's country",
    "doc_url": "https://docs.fintoc.com/reference/errors"
  }
}

Authorizations

Authorization

string

header

required

Body

application/json

customer

string

required

ID of the customer the invoice bills.

Example:

"cus_2c4mDe9NJyGmMzvCqLkXqAtjnRu"

lines

object[]

required

Line items the invoice bills for. All lines must share the same currency, which becomes the invoice currency.

Minimum array length: 1

Show child attributes

default_payment_method

string

Payment method Fintoc charges when the invoice is finalized. Required when collection_method is charge_automatically; optional with send_invoice. Must belong to the specified customer.

Example:

"pm_2c4mDhAbCdEfGhIjKlMnOpQrStu"

collection_method

enum<string>

The way Fintoc collects the invoice. One of charge_automatically (Fintoc charges default_payment_method once you finalize the invoice) or send_invoice (Fintoc leaves the invoice open for you to collect, through hosted_invoice_url or outside Fintoc). Defaults to charge_automatically.

Available options:

charge_automatically,

send_invoice

Example:

"send_invoice"

metadata

object

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

Example:

{ "order_id": "12345" }

business_profile

object

Business on whose behalf you collect the payment, for payment aggregators. Applied when Fintoc charges the invoice. Required if your organization identifies a business profile per payment.

Show child attributes

Response

The created invoice, in draft status.

string

required

Unique identifier of the invoice.

Example:

"inv_2bVdWxLpzXq8RkNcM3JtUv9AhTe"

hosted_invoice_url

string | null

required

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

Example:

"https://acme.billing.fintoc.com/invoices/inv_2bVdWxLpzXq8RkNcM3JtUv9AhTe"

object

any

required

Type of the object. Always invoice.

attempt_count

integer

required

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

Example:

1

collection_method

enum<string>

required

The way Fintoc collects the invoice. charge_automatically means Fintoc charges default_payment_method once the invoice is finalized. send_invoice means Fintoc leaves the invoice open for you to collect, through hosted_invoice_url or outside Fintoc. Subscription invoices inherit the collection method when issued and keep that collection method even if the subscription changes later.

Available options:

charge_automatically,

send_invoice

Example:

"send_invoice"

created_at

string<date-time>

required

ISO 8601 timestamp of when the invoice was created.

Example:

"2026-05-01T12:00:00Z"

currency

enum<string>

required

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

Available options:

CLP,

MXN

Example:

"CLP"

customer

string

required

id of the customer the invoice bills.

Example:

"cus_2bVdWyTnGq4PfLs7DkXjRm0CwIo"

default_payment_method

string | null

required

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

Example:

"pm_2c4mDhAbCdEfGhIjKlMnOpQrStu"

external_payment

boolean

required

Whether the invoice was settled with a payment collected outside Fintoc. false for invoices Fintoc collected, and for invoices that are not yet paid.

Example:

false

lines

object[]

required

Line items that make up the invoice total.

Show child attributes

metadata

object | null

required

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

mode

enum<string>

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.

Available options:

live,

test

Example:

"live"

next_payment_attempt_at

string<date-time> | null

required

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

Example:

"2026-05-02T12:00:00Z"

payments

object[]

required

Payment attempts to collect the invoice.

Show child attributes

status

enum<string>

required

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

Available options:

draft,

open,

paid,

void

Example:

"draft"

subscription

string | null

required

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

Example:

"sub_2bVdWzKfHr5QgMt8ElYkSn1DxJp"

total

integer

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:

30000

⌘I