---
title: "Create a charge"
method: POST
path: "/charges"
tags: ["Charges"]
---

# Create a charge

`POST /charges`

Creates a charge on an active subscription. The charge starts with status `pending`, and Fintoc collects the charge from the subscription's bank account on the next collection cycle. In `test` mode, Fintoc simulates the collection and updates the charge status asynchronously after creation.

## Request body

- object
  - `amount` integer, required — A positive integer in the smallest unit of `currency` (for example, `1000` for `$1000 CLP`, since CLP has no minor unit). The maximum depends on the bank of the subscription.
  - `currency` 'CLP', required — Three-letter ISO 4217 currency code. `CLP` is the only supported currency.
  - `subscription_id` string, required — The `id` of the subscription to charge. The subscription must be `active` and match the `live` or `test` mode of the API key used.
  - `business_profile` object — Business on whose behalf the charge is collected. Required for organizations that collect charges on behalf of enrolled merchants.
    - `category` string — Category of the enrolled merchant. In Chile, a 6-character activity code from the Servicio de Impuestos Internos.
    - `name` string — Name of the enrolled merchant. When set, this name appears as the recipient on the widget screens.
    - `tax_id` string — Chilean tax ID (RUT) of the enrolled merchant. Must be a valid RUT.
  - `metadata` object — Set of key-value pairs you can attach to the charge. Useful for storing additional information about the charge in a structured format.
  - `recipient_account` object — Bank account that receives the funds of the charge. Only used for organizations with recipient accounts enabled; otherwise it is ignored.
    - `holder_id` string, required — RUT of the account holder.
    - `institution_id` string, required — The `id` of the account's institution.
    - `number` string, required — Bank account number. Digits only, with no dashes or spaces.
    - `type` 'checking_account' | 'savings_account' | 'sight_account' | 'rut_account' | 'line_of_credit' | 'credit_card', required — Account type. One of `checking_account`, `savings_account`, `sight_account`, `rut_account`, `line_of_credit`, or `credit_card`.

## Response `201`

The created charge, with status `pending`. In `test` mode, the charge status updates asynchronously after creation to simulate the collection.

- SubscriptionsCharge — A charge is a single collection from the bank account of a subscription. You create a charge on an active subscription, and Fintoc collects the charge from the subscription's bank account on the next collection cycle. A charge starts as `pending` and ends as `succeeded`, `failed`, or `canceled`.
  - `id` string, required — Unique identifier of the charge.
  - `object` 'charge', required — Type of the object. Always `charge`.
  - `amount` integer, required — A positive integer in the smallest unit of `currency` (for example, `1000` for `$1000 CLP`, since CLP has no minor unit).
  - `created_at` string, date-time, required — ISO 8601 timestamp of when the charge was created.
  - `currency` string, required — Three-letter ISO 4217 currency code. `CLP` is the only supported currency.
  - `failure_code` 'insufficient_funds' | 'subscription_inactive' | 'charge_amount_limit_exceeded' | 'bank_account_unavailable' | 'other' | 'null', nullable, required — Reason why the charge failed. Always `null` unless `status` is `failed`. One of `insufficient_funds` (the bank account did not have enough funds), `subscription_inactive` (the subscription is no longer active at the bank), `charge_amount_limit_exceeded` (the amount exceeds the bank's per-charge limit), `bank_account_unavailable` (the bank account is closed, blocked, or could not be found), or `other`.
  - `metadata` object, required — Set of key-value pairs attached to the charge when it was created.
  - `mode` 'test' | 'live', required — Mode of the object. `live` objects use real institution data, `test` objects use fake data for integration testing.
  - `recipient_account` PayoutsRecipientAccount — Bank account that receives the payout.
    - `holder_id` string, required — Tax identifier of the account holder, without dots or hyphens (RUT in Chile, RFC in Mexico).
    - `institution_id` string, required — Fintoc identifier of the institution that holds the account, such as `cl_banco_estado`.
    - `number` string, required — Account number. In Mexico, an 18-digit CLABE (Clave Bancaria Estandarizada).
    - `type` 'checking_account' | 'sight_account' | 'rut_account' | 'fsa_account', required — Account subtype. One of `checking_account`, `sight_account` (Chilean cuenta vista), `rut_account` (BancoEstado CuentaRUT), or `fsa_account` (Mexican FSA account).
  - `status` 'pending' | 'in_progress' | 'succeeded' | 'failed' | 'canceled', required — Current state of the charge. One of `pending` (not yet sent to the bank), `in_progress` (being processed by the bank), `succeeded`, `failed`, or `canceled`.
  - `subscription_id` string, required — Identifier of the subscription the charge belongs to.

## Other responses

- `400` — Invalid request: a required parameter is missing or `recipient_account` is not valid.
- `401` — Invalid or missing API key.
- `403` — The subscription is inactive, the amount exceeds the subscription's bank limit, your organization does not have access to Charges, or your organization cannot use the subscriptions API.
- `404` — The subscription does not exist, belongs to a different organization, or does not match the `live` or `test` mode of the API key.

---

[API](https://skmtc.net/fintoc/apis/fintoc-api.md) · [All operations](https://skmtc.net/fintoc/apis/fintoc-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/fintoc/fintoc-api/revisions/9dafa63688a3/schema)