Sign in

v1

latestOpenAPI 3.1.02026-07-228956435.8 KB
Charges

Create a charge

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.

post/charges

Request body

amountinteger 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_idstring 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.

metadataobject

Set of key-value pairs you can attach to the charge. Useful for storing additional information about the charge in a structured format.

Example request

{
  "amount": 5000,
  "currency": "CLP",
  "subscription_id": "sub_m7N9rAWJS9dWDKEe",
  "business_profile": {
    "category": "620200",
    "name": "Hooli",
    "tax_id": "11111111-1"
  },
  "metadata": {
    "order_id": "0001"
  },
  "recipient_account": {
    "holder_id": "111111111",
    "institution_id": "cl_banco_de_chile",
    "number": "123123123",
    "type": "checking_account"
  }
}

Response

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

idstring required

Unique identifier of the charge.

object'charge' required

Type of the object. Always charge.

amountinteger required

A positive integer in the smallest unit of currency (for example, 1000 for $1000 CLP, since CLP has no minor unit).

created_atstring date-time required

ISO 8601 timestamp of when the charge was created.

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

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

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

Identifier of the subscription the charge belongs to.

Example response

{
  "id": "ch_o9YDuRzUez2GqV4x",
  "amount": 5000,
  "created_at": "2021-05-17T17:04:10.284Z",
  "currency": "CLP",
  "failure_code": "insufficient_funds",
  "metadata": {
    "order_id": "9182"
  },
  "mode": "live",
  "recipient_account": {
    "holder_id": "111111111",
    "institution_id": "cl_banco_estado",
    "number": "987654321",
    "type": "checking_account"
  },
  "status": "succeeded",
  "subscription_id": "sub_nMNejK7BT8oGbvO4"
}