---
title: "Create a checkout session"
method: POST
path: "/checkout_sessions"
tags: ["Checkout sessions"]
---

# Create a checkout session

`POST /checkout_sessions`

Creates a checkout session in the `live` or `test` mode of the API key used. The `flow` determines what the session does: `payment` collects a one-time payment, `subscription` starts a recurring subscription, and `setup` saves a payment method for future payments. Required fields depend on the flow. After creating the session, redirect your customer to the session's `redirect_url` or initialize the Fintoc widget with the session's `session_token`.

## Request body

- object
  - `amount` integer — Amount to charge your customer, in the smallest unit of `currency`. For `payment` flow sessions, provide either `amount` or `line_items`. Omit for `subscription` and `setup` flow sessions, where `amount` does not apply.
  - `business_profile` object — Business on whose behalf you collect the payment, for payment aggregators.
    - `category` string — Six-character merchant category code (MCC) of the business.
    - `name` string — Name of the business.
    - `tax_id` string — Tax identifier of the business.
  - `cancel_url` string — URL Fintoc redirects your customer to when the payment is not completed.
  - `currency` 'CLP' | 'MXN', required — Three-letter ISO 4217 currency code, in uppercase. One of `CLP` or `MXN`.
  - `customer` string — `id` of an existing customer to attach to the session. Cannot be combined with `customer_data`.
  - `customer_data` object — Data of a new customer to create and attach to the session. Cannot be combined with `customer`. You must provide either `email` or a complete `tax_id` (both `type` and `value`).
    - `address` object — Address of the customer.
      - `city` string — City.
      - `country` string — Two-letter country code (ISO 3166-1 alpha-2), case-insensitive.
      - `line1` string — Primary address line.
      - `line2` string — Secondary address line.
      - `postal_code` string — Postal or ZIP code.
      - `state` string — State or region.
    - `email` string — Email of the customer. Provide either `email` or `tax_id`.
    - `metadata` object — Set of key-value pairs to attach to the customer.
    - `name` string — Full name or business name of the customer.
    - `phone` string — Phone number of the customer in E.164 format, including the country code (for example `+56911111111`).
    - `tax_id` object — Tax identifier of the customer, either a Chilean tax ID (RUT) or a Mexican tax ID (RFC). Provide either `email` or `tax_id`. When provided, both `type` and `value` are required.
      - `type` 'cl_rut' | 'mx_rfc', required — Country-specific tax identifier format. One of `cl_rut` for Chilean tax ID (RUT) or `mx_rfc` for Mexican tax ID (RFC).
      - `value` string, required — Country-specific tax identification number. For `cl_rut`, use a Chilean tax ID (RUT) with or without dots and hyphens (for example `11.111.111-1` or `111111111`). For `mx_rfc`, use a Mexican tax ID (RFC).
  - `customer_email` string — Email of your customer, used to send the payment receipt.
  - `expires_at` string, date-time — ISO 8601 datetime, in UTC, of when the session expires. Must be at least 10 minutes in the future. Defaults to 24 hours after creation when omitted.
  - `flow` 'payment' | 'subscription' | 'setup' — Flow the session runs. One of `payment` (collects a one-time payment), `subscription` (starts a recurring subscription), or `setup` (saves a payment method for future payments). Defaults to `payment`.
  - `line_items` object[] — Items to charge for. Required for `subscription` flow sessions. For `payment` flow sessions, provide either `amount` or `line_items`.
    - `price_data` object, required — Price of the item.
      - `currency` string — Three-letter ISO 4217 currency code, in uppercase. `payment` flow items support `CLP` and `MXN`; `subscription` flow items support `CLP`, `CLF`, and `MXN`. Must match the top-level `currency`, except `CLF`, which is allowed in `CLP` subscription sessions.
      - `product` string — `id` of an existing product. Cannot be combined with `product_data`.
      - `product_data` object — Data of a new product to create. Cannot be combined with `product`.
        - `description` string — Description of the product.
        - `image_url` string — URL of the product image.
        - `name` string, required — Name of the product.
      - `recurring` object — Billing cadence of the price. Required for `subscription` flow items.
        - `interval` string — Billing frequency. One of `month` or `year`.
        - `interval_count` integer — Number of intervals between billings.
      - `unit_amount` integer — Amount per unit, in the smallest unit of `currency`.
    - `quantity` integer, required — Number of units of the item.
  - `metadata` object — Set of key-value pairs to attach to the session.
  - `payment_method` string — `id` of a saved payment method to pay the session with. Requires `customer` and `payment_method_types` of `["bank_transfer"]`.
  - `subscription` string — `id` of an existing subscription whose payment method this session updates once the customer completes it. Only for `setup` flow sessions.
  - `payment_method_options` object — Additional configuration of the session's payment methods, keyed by payment method type. Each key is one of your `payment_method_types`.
    - `bank_transfer` object — Options for `bank_transfer`.
      - `recipient_account` object — Account that receives the payment. Only for `payment` flow sessions.
      - `reference_number` string — Reference number to attach to the transfer. Only for `payment` flow sessions.
      - `sender_account` object — Restrictions on the account your customer pays or sets up the transfer from.
        - `holder_id` object — Identifier of the account holder, pre-filled in the widget. In `payment` flow `MXN` sessions the value must be a valid Mexican phone number. In `CLP` sessions it must be a valid Chilean tax ID (RUT).
          - `value` string, required — Identifier of the account holder.
          - `editable` boolean, required — If `false`, your customer cannot change the pre-filled value in the widget.
        - `institution_id` object — Institution your customer must pay or set up the transfer from. You can set this field only when `bank_transfer` is the only value in `payment_method_types`. In `payment` flow, omit it for `MXN` sessions.
          - `value` string, required — Identifier of the institution. For `CLP` sessions the value must be a valid Chilean bank code.
    - `pac` object — Options for `pac` (automatic recurring bank debit). Only for sessions with `flow` set to `setup` or `subscription` and `currency` set to `CLP`.
      - `sender_account` object — Restrictions on the account your customer subscribes with.
        - `types` string[] — Account types your customer can subscribe with. One of `checking_account`. Omit the field to apply no restriction; an empty array allows none.
        - `holder_id` object — Tax ID of the account holder, pre-filled in the widget. For `CLP` sessions the value must be a valid Chilean tax ID (RUT).
          - `value` string, required — Tax ID of the account holder.
          - `editable` boolean, required — If `false`, your customer cannot change the pre-filled value in the widget.
        - `institution_id` object — Institution your customer must use for the subscription. You can set this field only when `pac` is the only value in `payment_method_types`.
          - `value` string, required — Identifier of the institution. For `CLP` sessions the value must be a valid Chilean bank code.
    - `card` object — Options for `card`.
      - `types` string[] — Card providers the session accepts. One of `bank` or `hites`. Only for `payment` flow sessions, where it is required if you send `payment_method_options.card`. To apply no restriction, omit the `card` object entirely; do not send an empty array.
      - `kinds` string[] — Card kinds the session accepts. One of `credit` or `debit`. Only for `setup` and `subscription` flow sessions. Omit the field to allow every kind; an empty array allows none.
  - `payment_method_types` string[] — Payment method types your customer can use to pay the session. Valid values depend on the `flow`: `payment` accepts `card`, `bank_transfer`, and `installments`; `subscription` accepts `card` and `pac` (automatic recurring bank debit); `setup` accepts `card`, `bank_transfer`, and `pac`. In `MXN` sessions, `subscription` and `setup` flows accept only `card`. Defaults to the types your organization has enabled for the flow.
  - `save_payment_method` 'disabled' | 'enabled' — Whether to offer your customer the option to save their payment method for future payments. One of `enabled` or `disabled`. Only valid for `payment` flow sessions. When `enabled`, you must also provide `customer` or `customer_data`.
  - `success_url` string — URL Fintoc redirects your customer to after a successful payment.
  - `ui_mode` 'embedded' — UI mode for `payment` flow sessions. Set to `embedded` to initialize the Fintoc widget with the session's `session_token` instead of redirecting your customer. When `embedded`, you can omit both `success_url` and `cancel_url`.

## Response `201`

The created checkout session.

- CheckoutSession
  - `id` string, required — Unique identifier of the checkout session.
  - `object` 'checkout_session', required — Type of the object. Always `checkout_session`.
  - `amount` integer, nullable, required — Amount the session charges your customer, in the smallest unit of `currency`. For CLP the smallest unit is one peso (CLP has no decimals), so `350000` means $350,000 CLP. For MXN the smallest unit is one centavo, so `350000` means $3,500.00 MXN. `null` for `setup` and `subscription` flow sessions, which do not carry a single amount.
  - `business_profile` object, nullable, required — Business on whose behalf you collect the payment, for payment aggregators. `null` when the session was created without a business profile.
    - `category` string — Six-character merchant category code (MCC) of the business.
    - `name` string — Name of the business.
    - `tax_id` string — Tax identifier of the business.
  - `cancel_url` string, nullable, required — URL Fintoc redirects your customer to when the payment is not completed. `null` when the session was created without redirect URLs.
  - `created_at` string, date-time, required — ISO 8601 timestamp of when the checkout session was created.
  - `currency` 'CLP' | 'MXN', required — Three-letter ISO 4217 currency code, in uppercase. One of `CLP` or `MXN`.
  - `customer` object — Customer the session belongs to. This key is omitted (not `null`) when the session has no customer.
    - `id` string — Unique identifier of the customer.
    - `object` 'customer' — Type of the object. Always `customer`.
    - `address` object, nullable — Address of the customer. `null` when not provided. Keys without a value are omitted.
      - `city` string — City of the address.
      - `country` string — Country of the address, as a two-letter ISO 3166-1 code.
      - `line1` string — First line of the address.
      - `line2` string — Second line of the address.
      - `postal_code` string — Postal code of the address.
      - `state` string — State or region of the address.
    - `created_at` string, date-time — ISO 8601 timestamp of when the customer was created.
    - `email` string, nullable — Email of the customer. `null` when not provided.
    - `metadata` object — Set of key-value pairs attached to the customer.
    - `mode` 'test' | 'live' — Mode of the object. `live` objects use real institution data, `test` objects use fake data for integration testing.
    - `name` string, nullable — Name of the customer. `null` when not provided.
    - `phone` string, nullable — Phone number of the customer. `null` when not provided.
    - `tax_id` object, nullable — Tax identifier of the customer. `null` when not provided.
      - `type` string — Type of the tax identifier, for example `cl_rut`.
      - `value` string — Value of the tax identifier.
  - `customer_email` string, nullable, required — Email of your customer, used to send the payment receipt. `null` when not provided.
  - `expires_at` string, date-time, required — ISO 8601 timestamp of when the checkout session expires. After this time your customer can no longer pay the session.
  - `flow` 'payment' | 'subscription' | 'setup', required — Flow the session runs. One of `payment` (collects a one-time payment), `subscription` (starts a recurring subscription), or `setup` (saves a payment method for future payments).
  - `line_items` object[], nullable, required — Items the session charges for. `null` when the session was created without line items.
    - `price` object, required — Price of the item.
      - `currency` 'CLF' | 'CLP' | 'MXN', required — Three-letter ISO 4217 currency code, in uppercase. One of `CLP`, `MXN` or `CLF`.
      - `product` object, required — Product the price belongs to.
        - `description` string, nullable, required — Description of the product. `null` when not provided.
        - `image_url` string, nullable, required — URL of the product image. `null` when not provided.
        - `metadata` object, required — Set of key-value pairs attached to the product.
        - `name` string, required — Name of the product.
      - `recurring` object, nullable, required — Billing cadence of the price. `null` for one-time prices.
        - `interval` 'month' | 'year', required — Billing frequency. One of `month` or `year`.
        - `interval_count` integer, required — Number of intervals between billings. For example, `interval: month` with `interval_count: 3` bills every 3 months.
      - `unit_amount` integer, required — Amount per unit, in the smallest unit of `currency`.
    - `quantity` integer, required — Number of units of the item.
  - `metadata` object, required — Set of key-value pairs you attached to the session.
  - `mode` 'test' | 'live', required — Mode of the object. `live` objects use real institution data, `test` objects use fake data for integration testing.
  - `payment_method` string, nullable, required — `id` of the saved payment method that pays the session. `null` when the session is not paid with a previously saved payment method.
  - `payment_method_options` object, required — Configuration of the session's payment methods, keyed by payment method type. Each key matches one of `payment_method_types` and holds the options you set when creating the session, such as the `recipient_account` for `bank_transfer` or the `kinds` for `card`. See [`POST /v2/checkout_sessions`](https://docs.fintoc.com/reference/checkout-sessions-create) for the full shape.
  - `payment_method_types` string[], required — Payment method types your customer can use to pay the session. One or more of `card`, `bank_transfer`, `installments`, and `pac` (automatic recurring bank debit).
  - `payment_resource` object, nullable, required — Payment generated by the session. `null` until your customer starts a payment attempt.
    - `payment_intent` object, required — Payment intent of the session's active payment attempt.
      - `id` string, required — Unique identifier of the payment intent.
      - `object` 'payment_intent', required — Type of the object. Always `payment_intent`.
      - `amount` integer, required — Amount of the payment intent, in the smallest unit of `currency`. For CLP the smallest unit is one peso (CLP has no decimals), so `100000` means $100,000 CLP. For MXN the smallest unit is one centavo, so `7050` means $70.50 MXN.
      - `business_profile` object, nullable — Business on whose behalf you collect the payment, for payment aggregators. `null` when the payment was created without a business profile.
        - `category` string — Six-character merchant category code (MCC) of the business.
        - `name` string — Name of the business.
        - `tax_id` string — Tax identifier of the business.
      - `created_at` string, date-time, required — ISO 8601 timestamp of when the payment intent was created.
      - `currency` 'CLP' | 'MXN', required — Three-letter ISO 4217 currency code, in uppercase. One of `CLP` or `MXN`.
      - `customer` object, nullable, required — Customer the payment intent belongs to. `null` when the session was created without a customer.
        - `id` string — Unique identifier of the customer.
        - `object` 'customer' — Type of the object. Always `customer`.
        - `address` object, nullable — Address of the customer. `null` when not provided.
          - `city` string — City of the address.
          - `country` string — Country of the address, as a two-letter ISO 3166-1 code.
          - `line1` string — First line of the address.
          - `line2` string — Second line of the address.
          - `postal_code` string — Postal code of the address.
          - `state` string — State or region of the address.
        - `created_at` string, date-time — ISO 8601 timestamp of when the customer was created.
        - `email` string, nullable — Email of the customer. `null` when not provided.
        - `metadata` object — Set of key-value pairs attached to the customer.
        - `mode` 'test' | 'live' — Mode of the object. `live` objects use real institution data, `test` objects use fake data for integration testing.
        - `name` string, nullable — Name of the customer. `null` when not provided.
        - `phone` string, nullable — Phone number of the customer. `null` when not provided.
        - `tax_id` object, nullable — Tax identifier of the customer. `null` when not provided.
          - `type` string — Type of the tax identifier, for example `cl_rut`.
          - `value` string — Value of the tax identifier.
      - `customer_email` string, nullable, required — Email of your customer, used to send payment notifications. `null` when not provided.
      - `error_reason` string, nullable, required — Reason the payment failed, was rejected, or expired. `null` while the payment is in progress and when it succeeds.
      - `expires_at` string, date-time, nullable, required — ISO 8601 timestamp of when the payment expires and can no longer be paid. Only set for cash payments; `null` otherwise.
      - `metadata` object, required — Set of key-value pairs attached to the payment intent.
      - `mode` 'test' | 'live', required — Mode of the object. `live` objects use real institution data, `test` objects use fake data for integration testing.
      - `next_action` object, nullable, required — Action your customer must complete to continue the payment, as reported by the widget. `null` when no action is pending.
      - `payment_method` string, nullable, required — `id` of the payment method used to pay. `null` when the payment is not paid with a saved payment method.
      - `payment_type` string, required — Payment type used to pay. One of `bank_transfer` or `cash`.
      - `payment_type_options` object, required — Options specific to the payment type, keyed by payment type. For cash payments, contains a `cash` object with the details of the payment. Empty for bank transfers.
        - `cash` object — Details of the cash payment. Present only for cash payments.
          - `barcode_url` string, nullable, required — URL of the barcode your customer scans to pay in cash.
          - `reference_number` string, nullable, required — Reference number your customer uses to pay the cash payment.
          - `voucher_url` string, nullable, required — URL of the voucher your customer presents to pay in cash.
      - `recipient_account` object, nullable, required — Bank account that receives the payment. `null` for cash payments.
        - `holder_id` string, nullable, required — Tax identifier of the account holder. Chilean tax ID (RUT) in Chile, Mexican tax ID (RFC) in Mexico.
        - `institution_id` string, nullable, required — Identifier of the institution of the account.
        - `number` string, nullable, required — Number of the account. In Mexico, the standardized Mexican bank account number (CLABE).
        - `type` string, nullable, required — Type of the account, such as `checking_account` or `sight_account`.
      - `reference_id` string, nullable, required — Identifier of the transfer assigned by the institution. `null` until the transfer is executed.
      - `sender_account` object, nullable, required — Bank account your customer pays from. `null` until Fintoc identifies the sender.
        - `holder_id` string, nullable, required — Tax identifier of the account holder. Chilean tax ID (RUT) in Chile, Mexican tax ID (RFC) in Mexico.
        - `institution_id` string, nullable, required — Identifier of the institution of the account.
        - `number` string, nullable, required — Number of the account.
        - `type` string, nullable, required — Type of the account, such as `checking_account` or `sight_account`.
      - `status` 'created' | 'failed' | 'succeeded' | 'rejected' | 'in_progress' | 'pending' | 'expired', required — Lifecycle status of the payment intent. One of `created`, `in_progress`, `succeeded`, `rejected`, `failed`, `expired`, or `pending`. `pending` is only used when your organization has the pending status enabled.
      - `subscription` string, nullable, required — `id` of the subscription that originated the payment intent. `null` for one-time payments.
      - `transaction_date` string, date-time, nullable, required — ISO 8601 timestamp of when the institution executed the transfer. `null` until the transfer is executed.
      - `widget_token` string, nullable, required — Token used to initialize the Fintoc widget for this payment intent. Only returned when the payment intent is created; `null` in every other response.
  - `redirect_url` string, nullable, required — URL of the Fintoc-hosted checkout page where your customer completes the payment. Redirect your customer to this URL after creating the session. `null` for sessions paid through the Fintoc widget instead of a redirect.
  - `save_payment_method` 'disabled' | 'enabled' | 'null', nullable — Whether the session offers your customer the option to save their payment method for future payments. One of `enabled` or `disabled`. Only returned for `payment` flow sessions; `null` when not configured.
  - `session_token` string, nullable, required — Token used to initialize the Fintoc widget to pay the session. `null` for `subscription` and `setup` flow sessions and for payments completed outside the widget, like non-embedded card payments.
  - `setup_intent` string, nullable, required — Unique identifier for the setup intent created by `setup` and `subscription` flow sessions. `null` for other flows and until Fintoc attempts a setup. Retrieve the setup intent's status and error with the setup intent endpoint.
  - `status` 'created' | 'in_progress' | 'expired' | 'finished', required — Lifecycle status of the session. `created` until your customer starts paying, `in_progress` while Fintoc processes the payment, and `finished` or `expired` once the session succeeds or expires.
  - `subscription` string, nullable, required — `id` of the subscription started by a `subscription` flow session. `null` until the subscription is created and for other flows.
  - `success_url` string, nullable, required — URL Fintoc redirects your customer to after a successful payment. `null` when the session was created without redirect URLs.

## Other responses

- `400` — Invalid request: a required parameter is missing or invalid for the chosen flow.
- `401` — Unauthorized: the API key is missing or invalid.
- `403` — Forbidden: the requested flow is not allowed for your organization's configuration.
- `404` — Not found: the `payment_method`, `customer`, or `subscription` referenced in the request does not exist.
- `422` — Unprocessable entity: the `subscription` referenced in a `setup` flow session is canceled.

---

[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)