Sign in

v1

latestOpenAPI 3.1.02026-07-228956435.8 KB
Checkout sessions

Create a checkout session

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.

post/checkout_sessions

Request body

amountinteger

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.

cancel_urlstring

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.

customerstring

id of an existing customer to attach to the session. Cannot be combined with customer_data.

customer_emailstring

Email of your customer, used to send the payment receipt.

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

metadataobject

Set of key-value pairs to attach to the session.

payment_methodstring

id of a saved payment method to pay the session with. Requires customer and payment_method_types of ["bank_transfer"].

subscriptionstring

id of an existing subscription whose payment method this session updates once the customer completes it. Only for setup flow sessions.

payment_method_typesstring[]

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_urlstring

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.

Example request

{
  "amount": 350000,
  "business_profile": {
    "category": "541100",
    "name": "Test Business",
    "tax_id": "11.111.111-1"
  },
  "cancel_url": "https://merchant.com/cancel",
  "currency": "CLP",
  "customer": "cus_xK9mPq2RkV3WnDQG",
  "customer_data": {
    "address": {
      "city": "Santiago",
      "country": "CL",
      "line1": "Av. Providencia 123",
      "line2": "Depto 45",
      "postal_code": "7500000",
      "state": "RM"
    },
    "email": "customer@example.com",
    "name": "Felipe Castro",
    "phone": "+56911111111",
    "tax_id": {
      "type": "cl_rut",
      "value": "11111111-1"
    }
  },
  "customer_email": "customer@example.com",
  "expires_at": "2026-01-14T18:48:25Z",
  "flow": "payment",
  "line_items": [
    {
      "price_data": {
        "currency": "CLP",
        "product": "prod_xK9mPq2RkV3WnDQG",
        "product_data": {
          "description": "Monthly gym membership.",
          "image_url": "https://merchant.com/images/membership.png",
          "name": "Gym membership"
        },
        "recurring": {
          "interval": "month",
          "interval_count": 1
        },
        "unit_amount": 350000
      },
      "quantity": 1
    }
  ],
  "payment_method": "pm_xL9mPq2RkV3WnDQG",
  "subscription": "sub_xL9mPq2RkV3WnDQG",
  "payment_method_options": {
    "bank_transfer": {
      "reference_number": "1837127",
      "sender_account": {
        "institution_id": {
          "value": "cl_banco_de_chile"
        }
      }
    },
    "pac": {
      "sender_account": {
        "types": [
          "checking_account"
        ],
        "holder_id": {
          "value": "11.111.111-1"
        },
        "institution_id": {
          "value": "cl_banco_de_chile"
        }
      }
    },
    "card": {
      "types": [
        "bank"
      ],
      "kinds": [
        "debit"
      ]
    }
  },
  "payment_method_types": [
    "bank_transfer"
  ],
  "save_payment_method": "enabled",
  "success_url": "https://merchant.com/success",
  "ui_mode": "embedded"
}

Response

The created checkout session.

idstring required

Unique identifier of the checkout session.

object'checkout_session' required

Type of the object. Always checkout_session.

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

cancel_urlstring nullable required

URL Fintoc redirects your customer to when the payment is not completed. null when the session was created without redirect URLs.

created_atstring 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_emailstring nullable required

Email of your customer, used to send the payment receipt. null when not provided.

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

metadataobject 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_methodstring 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_optionsobject 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 for the full shape.

payment_method_typesstring[] 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).

redirect_urlstring 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_tokenstring 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_intentstring 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.

subscriptionstring nullable required

id of the subscription started by a subscription flow session. null until the subscription is created and for other flows.

success_urlstring nullable required

URL Fintoc redirects your customer to after a successful payment. null when the session was created without redirect URLs.

Example response

{
  "id": "cs_li5531onlFDi235",
  "amount": 350000,
  "business_profile": {
    "category": "541100",
    "name": "Test Business",
    "tax_id": "111111111"
  },
  "cancel_url": "https://merchant.com/cancel",
  "created_at": "2026-01-13T18:48:25Z",
  "currency": "CLP",
  "customer": {
    "id": "cus_xK9mPq2RkV3WnDQG",
    "address": {
      "city": "Santiago",
      "country": "cl",
      "line1": "Av. Providencia 123",
      "line2": "Depto 45",
      "postal_code": "7500000",
      "state": "RM"
    },
    "created_at": "2026-01-10T12:30:00Z",
    "email": "customer@example.com",
    "mode": "live",
    "name": "Felipe Castro",
    "phone": "+56912345678",
    "tax_id": {
      "type": "cl_rut",
      "value": "111111111"
    }
  },
  "customer_email": "customer@example.com",
  "expires_at": "2026-01-14T18:48:25Z",
  "flow": "payment",
  "line_items": [
    {
      "price": {
        "currency": "CLP",
        "product": {
          "description": "Monthly gym membership.",
          "image_url": "https://merchant.com/images/membership.png",
          "name": "Gym membership"
        },
        "recurring": {
          "interval": "month",
          "interval_count": 1
        },
        "unit_amount": 350000
      },
      "quantity": 1
    }
  ],
  "mode": "live",
  "payment_method": "pm_xL9mPq2RkV3WnDQG",
  "payment_method_types": [
    "bank_transfer"
  ],
  "payment_resource": {
    "payment_intent": {
      "id": "pi_BO381oEATXonG6bj",
      "amount": 100000,
      "created_at": "2026-01-13T18:48:25Z",
      "currency": "CLP",
      "customer": {
        "mode": "live"
      },
      "customer_email": "customer@example.com",
      "error_reason": "insufficient_funds",
      "metadata": {
        "order_id": "9182"
      },
      "mode": "live",
      "payment_method": "pm_1x7vKQ8oEATXonG6",
      "payment_type": "bank_transfer",
      "payment_type_options": {},
      "reference_id": "90123712",
      "status": "succeeded",
      "subscription": "sub_dJOd4hcZby9XK1Lm",
      "transaction_date": "2026-01-13T18:50:25Z",
      "widget_token": "pi_BO381oEATXonG6bj_sec_aBcDeFgHiJkLmNoP"
    }
  },
  "redirect_url": "https://pay.fintoc.com/cs_li5531onlFDi235",
  "save_payment_method": "enabled",
  "session_token": "eyJhbGciOiJIUzI1NiJ9.eyJpZCI6ImNzX2xpNTUzMSJ9.iV2qAVrqYLuqxF4",
  "setup_intent": "seti_xL9mPq2RkV3WnDQG",
  "status": "created",
  "subscription": "sub_xL9mPq2RkV3WnDQG",
  "success_url": "https://merchant.com/success"
}