> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fintoc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a subscription intent

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

**`v1`** · Base URL `https://api.fintoc.com/v1`


## OpenAPI

````yaml reference/fintoc-api.json POST /subscription_intents
openapi: 3.1.0
info:
  title: fintoc-api
  version: v2026-02-01
servers:
  - url: https://api.fintoc.com/v1
security: []
paths:
  /subscription_intents:
    post:
      tags:
        - Subscription intents
      summary: Create a subscription intent
      description: >-
        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.
      operationId: subscription-intents-create
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                business_profile:
                  type: object
                  description: Information shown to the payer in the widget.
                  properties:
                    name:
                      type: string
                      description: >-
                        Name displayed to the payer as the subscription's
                        recipient.
                      example: Hooli
                  required:
                    - name
                customer_email:
                  type: string
                  description: >-
                    Email address of the payer. Fintoc sends the subscription
                    receipt to this address when the subscription intent
                    succeeds.
                  example: payer@example.com
                reference_id:
                  type: string
                  description: >-
                    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`.
                  example: ABC12345
            examples:
              create_subscription_intent:
                summary: Create a subscription intent
                value:
                  business_profile:
                    name: Hooli
                  customer_email: payer@example.com
                  reference_id: ABC12345
      responses:
        '201':
          description: >-
            The created subscription intent. `widget_token` is only returned in
            this response.
          content:
            application/json:
              examples:
                subscription_intent_created:
                  value:
                    id: si_mceqLoFwfBVHi3q4
                    object: subscription_intent
                    business_profile:
                      name: Hooli
                    created_at: '2023-03-08T15:24:11Z'
                    customer_email: payer@example.com
                    mode: live
                    public_error: null
                    reference_id: ABC12345
                    status: created
                    subscription: null
                    widget_token: si_mceqLoFwfBVHi3q4_sec_a8Mw9bnHzgVRCMTSDgrJpvkN
              schema:
                $ref: '#/components/schemas/subscriptions_subscription_intent'
        '400':
          description: >-
            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.
          content:
            application/json:
              examples:
                invalid_reference_id_format:
                  value:
                    error:
                      type: invalid_request_error
                      code: invalid_reference_id_format
                      param: reference_id
                      message: >-
                        Invalid id format. Should only contain numbers and
                        uppercase letters: abc123
                      doc_url: https://docs.fintoc.com/reference/errors
              schema:
                $ref: '#/components/schemas/error_object'
        '401':
          description: Invalid or missing API key.
          content:
            application/json:
              examples:
                invalid_api_key:
                  value:
                    error:
                      type: authentication_error
                      code: invalid_api_key
                      message: 'Invalid API Key: invalid-*oken'
              schema:
                $ref: '#/components/schemas/error_object'
        '403':
          description: >-
            Your organization does not have access to the Subscriptions product
            in `live` mode.
          content:
            application/json:
              examples:
                product_access_required:
                  value:
                    error:
                      type: authorization_error
                      code: product_access_required
                      param: null
                      message: >-
                        Your organization does not have access to the
                        'Subscriptions' product. Send an email to
                        sales@fintoc.com to hire this product.
                      doc_url: https://docs.fintoc.com/reference/errors
              schema:
                $ref: '#/components/schemas/error_object'
      security:
        - api_key: []
components:
  schemas:
    subscriptions_subscription_intent:
      type: object
      description: >-
        Represents the flow a payer goes through to authorize a subscription at
        their bank. A successful subscription intent produces a `Subscription`.
      properties:
        id:
          type: string
          description: Unique identifier of the subscription intent.
          example: si_mceqLoFwfBVHi3q4
        object:
          const: subscription_intent
          description: Type of the object. Always `subscription_intent`.
        business_profile:
          description: >-
            Information shown to the payer in the widget. `null` when not
            provided on creation.
          anyOf:
            - type: 'null'
            - type: object
              properties:
                name:
                  type: string
                  description: Name displayed to the payer as the subscription's recipient.
                  example: Hooli
              required:
                - name
        created_at:
          type: string
          format: date-time
          description: >-
            ISO 8601 timestamp, in UTC, of when the subscription intent was
            created.
          example: '2023-03-08T15:24:11Z'
        customer_email:
          type:
            - string
            - 'null'
          description: >-
            Email address of the payer. Fintoc sends the subscription receipt to
            this address when the subscription intent succeeds.
          example: payer@example.com
        mode:
          $ref: '#/components/schemas/mode'
        public_error:
          type:
            - string
            - 'null'
          enum:
            - 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
          description: >-
            Error code describing why the subscription intent did not succeed.
            `null` unless `status` is `failed` or `rejected`.
          example: login_invalid_credentials
        reference_id:
          type:
            - string
            - 'null'
          description: >-
            Identifier the payer's bank uses to display the subscription on the
            bank's portal. `null` when not provided on creation.
          example: ABC12345
        status:
          type: string
          enum:
            - created
            - in_progress
            - succeeded
            - failed
            - rejected
          description: >-
            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).
          example: succeeded
        subscription:
          description: >-
            `Subscription` created when the subscription intent succeeds. `null`
            in every other status.
          anyOf:
            - type: 'null'
            - $ref: '#/components/schemas/subscriptions_subscription'
        widget_token:
          type:
            - string
            - 'null'
          description: >-
            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.
          example: si_mceqLoFwfBVHi3q4_sec_a8Mw9bnHzgVRCMTSDgrJpvkN
      required:
        - id
        - object
        - business_profile
        - created_at
        - customer_email
        - mode
        - public_error
        - reference_id
        - status
        - subscription
        - widget_token
    error_object:
      type: object
      properties:
        error:
          type: object
          description: Details of the error that caused the request to fail.
          properties:
            code:
              type: string
              description: >-
                Machine-readable code identifying the specific error, for
                example `invalid_api_key`. Not returned by every error.
              example: invalid_api_key
            doc_url:
              type: string
              description: >-
                URL of a documentation page with more details about the error.
                Not returned by every error.
              example: https://docs.fintoc.com/reference/errors
            message:
              type: string
              description: Human-readable message describing the error.
              example: 'Invalid API Key: invalid-*oken'
            param:
              type:
                - string
                - 'null'
              description: >-
                Name of the request parameter that caused the error. `null` when
                the error cannot be tied to a single parameter, and not returned
                by every error.
              example: amount
            type:
              type: string
              description: >-
                Category of the error, for example `invalid_request_error`,
                `authentication_error`, or `api_error`.
              example: invalid_request_error
          required:
            - type
            - message
    mode:
      type: string
      enum:
        - test
        - live
      description: >-
        Mode of the object. `live` objects use real institution data, `test`
        objects use fake data for integration testing.
      example: live
    subscriptions_subscription:
      type: object
      description: >-
        Represents a payer's authorization to charge a bank account. Fintoc
        creates a `Subscription` when a `SubscriptionIntent` succeeds, and an
        `active` subscription accepts charges.
      properties:
        id:
          type: string
          description: Unique identifier of the subscription.
          example: sub_m7N9rAWJS9dWDKEe
        object:
          const: subscription
          description: Type of the object. Always `subscription`.
        account:
          $ref: '#/components/schemas/subscriptions_account'
        created_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp, in UTC, of when the subscription was created.
          example: '2023-03-08T15:24:11Z'
        mode:
          $ref: '#/components/schemas/mode'
        reference_id:
          type: string
          description: >-
            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.
          example: ABC12345
        status:
          type: string
          enum:
            - pending
            - active
            - canceled
          description: >-
            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).
          example: active
      required:
        - id
        - object
        - account
        - created_at
        - mode
        - reference_id
        - status
    subscriptions_account:
      type: object
      description: Represents the bank account a payer authorized for a subscription.
      properties:
        id:
          type: string
          description: Unique identifier of the account.
          example: acc_nMNejK7BT8oGbvO4
        object:
          const: account
          description: Type of the object. Always `account`.
        balance:
          description: >-
            Balance of the account. Always `null` in API responses; only present
            in webhook event payloads.
          anyOf:
            - type: 'null'
            - $ref: '#/components/schemas/balance'
        currency:
          type: string
          pattern: ^[A-Z]{3}$
          description: Three-letter ISO 4217 currency code of the account.
          example: CLP
        holder_id:
          type: string
          description: >-
            Fiscal identifier of the account holder, without dots or dashes. For
            Chilean accounts, the Chilean tax ID (RUT).
          example: '111111111'
        holder_name:
          type: string
          description: Name of the account holder, as registered at the bank.
          example: Jon Snow
        institution:
          $ref: '#/components/schemas/institution'
        name:
          type: string
          description: Display name of the account.
          example: Cuenta Corriente
        number:
          type: string
          description: Bank account number.
          example: '9530516286'
        official_name:
          type: string
          description: Official product name the bank gives to the account.
          example: Cuenta Corriente Moneda Local
        type:
          $ref: '#/components/schemas/account_type'
      required:
        - id
        - object
        - balance
        - currency
        - holder_id
        - holder_name
        - institution
        - name
        - number
        - official_name
        - type
    balance:
      type: object
      description: >-
        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).
      properties:
        available:
          type: integer
          description: Amount available to spend, including overdraft lines if any.
          example: 500000
        current:
          type: integer
          description: >-
            Amount of money owned by the account holder, without overdraft
            lines.
          example: 500000
        limit:
          type: integer
          description: Maximum amount available to spend, including credit lines.
          example: 500000
      required:
        - available
        - current
        - limit
    institution:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the institution.
          example: cl_banco_de_chile
        country:
          type: string
          description: ISO 3166-1 alpha-2 code of the country of the institution.
          example: cl
        name:
          type: string
          description: Name of the institution.
          example: Banco de Chile
      required:
        - id
        - country
        - name
    account_type:
      type: string
      enum:
        - checking_account
        - savings_account
        - sight_account
        - line_of_credit
        - credit_card
      description: Type of the account. Fintoc exposes RUT accounts as `sight_account`.
      example: checking_account
  securitySchemes:
    api_key:
      type: apiKey
      name: Authorization
      in: header

````