---
title: "Create a subscription intent"
method: POST
path: "/subscription_intents"
tags: ["Subscription intents"]
---

# Create a subscription intent

`POST /subscription_intents`

Creates a subscription intent in the `live` or `test` mode of the API key used. The response includes the `widget_token` used to open the widget so the payer can authorize the subscription.

## Request body

- object
  - `business_profile` object — Information shown to the payer in the widget.
    - `name` string, required — Name displayed to the payer as the subscription's recipient.
  - `customer_email` string — Email address of the payer. Fintoc sends the subscription receipt to this address when the subscription intent succeeds.
  - `reference_id` string — Identifier the payer's bank uses to display the subscription on the bank's portal. Up to 15 characters, uppercase letters and numbers only, and not already in use by another subscription intent that has not failed. When omitted, `reference_id` is `null` on the subscription intent and defaults to the account holder's ID on the resulting `Subscription`.

## Response `201`

The created subscription intent. `widget_token` is only returned in this response.

- SubscriptionsSubscriptionIntent — Represents the flow a payer goes through to authorize a subscription at their bank. A successful subscription intent produces a `Subscription`.
  - `id` string, required — Unique identifier of the subscription intent.
  - `object` 'subscription_intent', required — Type of the object. Always `subscription_intent`.
  - `business_profile` object, nullable, required — Information shown to the payer in the widget. `null` when not provided on creation.
    - `name` string, required — Name displayed to the payer as the subscription's recipient.
  - `created_at` string, date-time, required — ISO 8601 timestamp, in UTC, of when the subscription intent was created.
  - `customer_email` string, nullable, required — Email address of the payer. Fintoc sends the subscription receipt to this address when the subscription intent succeeds.
  - `mode` 'test' | 'live', required — Mode of the object. `live` objects use real institution data, `test` objects use fake data for integration testing.
  - `public_error` 'null' | 'login_invalid_credentials' | 'login_credentials_locked' | 'authorization_timeout' | 'mfa_authorization_timeout' | 'mfa_unavailable' | 'bank_connection_error' | 'bank_not_available' | 'password_change_required' | 'request_timeout' | 'subscription_intent_expired' | 'account_type_not_permitted' | 'internal_error' | 'user_left', nullable, required — Error code describing why the subscription intent did not succeed. `null` unless `status` is `failed` or `rejected`.
  - `reference_id` string, nullable, required — Identifier the payer's bank uses to display the subscription on the bank's portal. `null` when not provided on creation.
  - `status` 'created' | 'in_progress' | 'succeeded' | 'failed' | 'rejected', required — Status of the subscription intent. One of `created` (waiting for the payer to start the authorization), `in_progress` (the payer is authorizing the subscription at their bank), `succeeded` (the payer authorized the subscription), `failed` (the authorization failed or expired), or `rejected` (the payer's bank rejected the subscription).
  - `subscription` SubscriptionsSubscription, required — Represents a payer's authorization to charge a bank account. Fintoc creates a `Subscription` when a `SubscriptionIntent` succeeds, and an `active` subscription accepts charges.
    - `id` string, required — Unique identifier of the subscription.
    - `object` 'subscription', required — Type of the object. Always `subscription`.
    - `account` SubscriptionsAccount, required — Represents the bank account a payer authorized for a subscription.
      - `id` string, required — Unique identifier of the account.
      - `object` 'account', required — Type of the object. Always `account`.
      - `balance` Balance, required — Balance of the account, as reported by the institution. All amounts are in the smallest unit of the account's currency (CLP has no decimals, so amounts are in pesos).
        - `available` integer, required — Amount available to spend, including overdraft lines if any.
        - `current` integer, required — Amount of money owned by the account holder, without overdraft lines.
        - `limit` integer, required — Maximum amount available to spend, including credit lines.
      - `currency` string, required — Three-letter ISO 4217 currency code of the account.
      - `holder_id` string, required — Fiscal identifier of the account holder, without dots or dashes. For Chilean accounts, the Chilean tax ID (RUT).
      - `holder_name` string, required — Name of the account holder, as registered at the bank.
      - `institution` Institution, required
        - `id` string, required — Unique identifier of the institution.
        - `country` string, required — ISO 3166-1 alpha-2 code of the country of the institution.
        - `name` string, required — Name of the institution.
      - `name` string, required — Display name of the account.
      - `number` string, required — Bank account number.
      - `official_name` string, required — Official product name the bank gives to the account.
      - `type` 'checking_account' | 'savings_account' | 'sight_account' | 'line_of_credit' | 'credit_card', required — Type of the account. Fintoc exposes RUT accounts as `sight_account`.
    - `created_at` string, date-time, required — ISO 8601 timestamp, in UTC, of when the subscription was created.
    - `mode` 'test' | 'live', required — Mode of the object. `live` objects use real institution data, `test` objects use fake data for integration testing.
    - `reference_id` string, required — Identifier the payer's bank uses to display the subscription on the bank's portal. Defaults to the account holder's ID when not provided on creation.
    - `status` 'pending' | 'active' | 'canceled', required — Status of the subscription. One of `pending` (the bank has not confirmed the subscription yet), `active` (the subscription accepts charges), or `canceled` (the subscription no longer accepts charges).
  - `widget_token` string, nullable, required — Token used to open the widget so the payer can authorize the subscription. Only returned when the subscription intent is created; `null` in every other response.

## Other responses

- `400` — Invalid request: `business_profile` has no `name`, `customer_email` is not a valid email address, or `reference_id` does not meet the format, length, or uniqueness constraints.
- `401` — Invalid or missing API key.
- `403` — Your organization does not have access to the Subscriptions product in `live` mode.

---

[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/versions/9dafa63688a3/schema)