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

# Create checkout session



## OpenAPI

````yaml /api-reference/openapi.json post /checkout/sessions
openapi: 3.0.1
info:
  title: Tirdad API
  description: Tirdad API Service
  contact:
    name: API Support
  version: '1.0'
servers:
  - url: https://api.tirdad.ai/v1
    description: Tirdad API
security: []
paths:
  /checkout/sessions:
    post:
      tags:
        - Checkout
      summary: Create checkout session
      operationId: createCheckoutSession
      requestBody:
        description: Checkout session to create
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCheckoutSessionRequest'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckoutSessionResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors.ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors.ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors.ErrorResponse'
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: go
          label: Go
          source: "package main\n\nimport(\n\t\"context\"\n\ttirdad \"github.com/tirdad-billing/go-sdk/v2\"\n\t\"github.com/tirdad-billing/go-sdk/v2/models/types\"\n\t\"log\"\n)\n\nfunc main() {\n    ctx := context.Background()\n\n    s := tirdad.New(\n        tirdad.WithSecurity(\"<YOUR_API_KEY_HERE>\"),\n    )\n\n    res, err := s.Checkout.CreateCheckoutSession(ctx, types.CreateCheckoutSessionRequest{\n        Action: types.CheckoutActionPayInvoice,\n        CustomerExternalID: \"<id>\",\n        PaymentProvider: types.CheckoutPaymentProviderRazorpay,\n    })\n    if err != nil {\n        log.Fatal(err)\n    }\n    if res.CheckoutSessionResponse != nil {\n        // handle response\n    }\n}"
        - lang: python
          label: Python
          source: |-
            from tirdad_sdk import Tirdad


            with Tirdad(
                api_key_auth="<YOUR_API_KEY_HERE>",
            ) as f_client:

                res = f_client.checkout.create_checkout_session(action="pay_invoice", customer_external_id="<id>", payment_provider="razorpay")

                # Handle response
                print(res)
        - lang: typescript
          label: TypeScript
          source: |-
            import { Tirdad } from "@tirdad/sdk";

            const tirdad = new Tirdad({
              apiKeyAuth: "<YOUR_API_KEY_HERE>",
            });

            async function run() {
              const result = await tirdad.checkout.createCheckoutSession({
                action: "pay_invoice",
                customerExternalId: "<id>",
                paymentProvider: "razorpay",
              });

              console.log(result);
            }

            run();
components:
  schemas:
    CreateCheckoutSessionRequest:
      required:
        - action
        - customer_external_id
        - payment_provider
      type: object
      properties:
        action:
          $ref: '#/components/schemas/types.CheckoutAction'
        cancel_url:
          type: string
        configuration:
          $ref: '#/components/schemas/types.CheckoutConfiguration'
        customer_external_id:
          type: string
        entity_creation_options:
          $ref: '#/components/schemas/EntityCreationOptions'
        failure_url:
          type: string
        idempotency_key:
          type: string
        metadata:
          type: object
          additionalProperties:
            type: string
        payment_provider:
          $ref: '#/components/schemas/types.CheckoutPaymentProvider'
        payment_provider_config:
          $ref: '#/components/schemas/types.CheckoutPaymentProviderConfig'
        success_url:
          type: string
    CheckoutSessionResponse:
      type: object
      properties:
        action:
          $ref: '#/components/schemas/types.CheckoutAction'
        cancel_url:
          type: string
        cancelled_at:
          type: string
          format: date-time
        checkout_invoice_id:
          type: string
        checkout_payment_id:
          type: string
        checkout_status:
          $ref: '#/components/schemas/types.CheckoutStatus'
        completed_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
        customer_id:
          type: string
        entity_creation_result:
          $ref: '#/components/schemas/EntityCreationResult'
        expires_at:
          type: string
          format: date-time
        failure_reason:
          type: string
        failure_url:
          type: string
        id:
          type: string
        idempotency_key:
          type: string
        metadata:
          $ref: '#/components/schemas/types.Metadata'
        next_poll_after_ms:
          type: integer
          description: >-
            NextPollAfterMs is how long a client should wait before reading
            again.

            Zero means stop — either the session is terminal, or this response
            did not

            come from a polling read.
        payment:
          $ref: '#/components/schemas/CheckoutPaymentBlock'
        payment_action:
          $ref: '#/components/schemas/types.PaymentAction'
        payment_provider:
          $ref: '#/components/schemas/types.CheckoutPaymentProvider'
        stale:
          type: boolean
          description: >-
            Stale reports that this response is stored state that was not
            checked against

            the payment provider on this request — the read was debounced, or
            the gateway

            did not answer. A UI should say "still checking" rather than
            presenting a

            stale answer as fact.
        success_url:
          type: string
        terminal:
          type: boolean
          description: >-
            Terminal reports whether the session has finished. Clients poll
            until this is

            true rather than hardcoding the status set, which would go stale if
            a status

            is ever added.
        updated_at:
          type: string
          format: date-time
    errors.ErrorResponse:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/errors.ErrorCode'
        http_status_code:
          type: integer
        message:
          type: string
      x-speakeasy-name-override: ErrorResponse
    types.CheckoutAction:
      type: string
      enum:
        - create_subscription
        - modify_subscription
        - wallet_topup
        - add_addon
        - pay_invoice
      x-enum-varnames:
        - CheckoutActionCreateSubscription
        - CheckoutActionModifySubscription
        - CheckoutActionWalletTopup
        - CheckoutActionAddAddon
        - CheckoutActionPayInvoice
      x-speakeasy-name-override: CheckoutAction
    types.CheckoutConfiguration:
      type: object
      properties:
        add_addon_batch_params:
          type: array
          items:
            $ref: '#/components/schemas/types.AddAddonParams'
        add_addon_params:
          $ref: '#/components/schemas/types.AddAddonParams'
        create_subscription_params:
          $ref: '#/components/schemas/types.CreateSubscriptionParams'
        modify_subscription_params:
          $ref: '#/components/schemas/types.ModifySubscriptionParams'
        pay_invoice_params:
          $ref: '#/components/schemas/types.PayInvoiceParams'
        wallet_topup_params:
          $ref: '#/components/schemas/types.WalletTopupParams'
      x-speakeasy-name-override: CheckoutConfiguration
    EntityCreationOptions:
      type: object
      properties:
        entity_creation_conflict_policies:
          $ref: '#/components/schemas/EntityCreationConflictPolicies'
    types.CheckoutPaymentProvider:
      type: string
      enum:
        - razorpay
        - chargebee
        - stripe
      x-enum-varnames:
        - CheckoutPaymentProviderRazorpay
        - CheckoutPaymentProviderChargebee
        - CheckoutPaymentProviderStripe
      x-speakeasy-name-override: CheckoutPaymentProvider
    types.CheckoutPaymentProviderConfig:
      type: object
      properties:
        collection_method:
          $ref: '#/components/schemas/types.CollectionMethod'
        customer_not_present:
          type: boolean
          description: >-
            CustomerNotPresent is the unattended/MIT opt-in. Zero value
            (omitted) means

            the customer is present, so a missed auto-charge may fall back to a
            hosted

            authorization link. Set true only from merchant-initiated paths
            (auto top-up).
        max_mandate_limit:
          type: string
        payment_method:
          $ref: '#/components/schemas/types.PaymentMethodType'
      x-speakeasy-name-override: CheckoutPaymentProviderConfig
    types.CheckoutStatus:
      type: string
      enum:
        - initiated
        - pending
        - completed
        - failed
        - expired
      x-enum-varnames:
        - CheckoutStatusInitiated
        - CheckoutStatusPending
        - CheckoutStatusCompleted
        - CheckoutStatusFailed
        - CheckoutStatusExpired
      x-speakeasy-name-override: CheckoutStatus
    EntityCreationResult:
      type: object
      properties:
        entity_id:
          type: string
        status:
          $ref: '#/components/schemas/types.EntityCreationStatus'
    types.Metadata:
      type: object
      additionalProperties:
        type: string
      x-speakeasy-name-override: Metadata
    CheckoutPaymentBlock:
      type: object
      properties:
        gateway:
          type: string
        id:
          type: string
        status:
          $ref: '#/components/schemas/types.PaymentStatus'
    types.PaymentAction:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/types.PaymentActionType'
        url:
          type: string
      x-speakeasy-name-override: PaymentAction
    errors.ErrorCode:
      type: string
      enum:
        - http_client_error
        - system_error
        - internal_error
        - not_found
        - already_exists
        - version_conflict
        - validation_error
        - invalid_operation
        - permission_denied
        - database_error
        - service_unavailable
        - too_many_requests
        - not_implemented
      x-enum-varnames:
        - ErrCodeHTTPClient
        - ErrCodeSystemError
        - ErrCodeInternalError
        - ErrCodeNotFound
        - ErrCodeAlreadyExists
        - ErrCodeVersionConflict
        - ErrCodeValidation
        - ErrCodeInvalidOperation
        - ErrCodePermissionDenied
        - ErrCodeDatabase
        - ErrCodeServiceUnavailable
        - ErrCodeTooManyRequests
        - ErrCodeNotImplemented
      x-speakeasy-name-override: ErrorCode
    types.AddAddonParams:
      type: object
      properties:
        addons:
          type: array
          items:
            $ref: '#/components/schemas/types.AddAddonRef'
        removes:
          type: array
          items:
            $ref: '#/components/schemas/types.RemoveAddonRef'
        subscription_id:
          type: string
      x-speakeasy-name-override: AddAddonParams
    types.CreateSubscriptionParams:
      type: object
      properties:
        billing_period:
          $ref: '#/components/schemas/types.BillingPeriod'
        currency:
          type: string
        end_date:
          type: string
          format: date-time
        lookup_key:
          type: string
        metadata:
          type: object
          additionalProperties:
            type: string
        plan_id:
          type: string
        start_date:
          type: string
          format: date-time
        subscription_id:
          type: string
      x-speakeasy-name-override: CreateSubscriptionParams
    types.ModifySubscriptionParams:
      type: object
      properties:
        line_item_modifications:
          type: array
          items:
            $ref: '#/components/schemas/types.ModifySubscriptionLineItem'
        modify_type:
          $ref: '#/components/schemas/types.ModifySubscriptionType'
        subscription_id:
          type: string
        trial_end_at:
          type: string
          description: >-
            TrialEndAt is where a trial_end checkout starts the first paid
            period.
          format: date-time
      x-speakeasy-name-override: ModifySubscriptionParams
    types.PayInvoiceParams:
      required:
        - invoice_id
      type: object
      properties:
        invoice_id:
          type: string
      x-speakeasy-name-override: PayInvoiceParams
    types.WalletTopupParams:
      required:
        - wallet_id
      type: object
      properties:
        wallet_id:
          type: string
        wallet_transaction_id:
          type: string
      x-speakeasy-name-override: WalletTopupParams
    EntityCreationConflictPolicies:
      type: object
      properties:
        on_existing_entity:
          $ref: '#/components/schemas/types.OnExistingEntityPolicy'
    types.CollectionMethod:
      type: string
      enum:
        - charge_automatically
        - send_invoice
      x-enum-varnames:
        - CollectionMethodChargeAutomatically
        - CollectionMethodSendInvoice
      x-speakeasy-name-override: CollectionMethod
    types.PaymentMethodType:
      type: string
      enum:
        - CARD
        - ACH
        - OFFLINE
        - CREDITS
        - PAYMENT_LINK
        - UPI
      x-enum-varnames:
        - PaymentMethodTypeCard
        - PaymentMethodTypeACH
        - PaymentMethodTypeOffline
        - PaymentMethodTypeCredits
        - PaymentMethodTypePaymentLink
        - PaymentMethodTypeUPI
      x-speakeasy-name-override: PaymentMethodType
    types.EntityCreationStatus:
      type: string
      enum:
        - created
        - superseded
        - failed_already_exists
      x-enum-varnames:
        - EntityCreationStatusCreated
        - EntityCreationStatusSuperseded
        - EntityCreationStatusFailedAlreadyExists
      x-speakeasy-name-override: EntityCreationStatus
    types.PaymentStatus:
      type: string
      enum:
        - INITIATED
        - PENDING
        - PROCESSING
        - SUCCEEDED
        - OVERPAID
        - FAILED
        - REFUNDED
        - PARTIALLY_REFUNDED
        - VOIDED
      x-enum-varnames:
        - PaymentStatusInitiated
        - PaymentStatusPending
        - PaymentStatusProcessing
        - PaymentStatusSucceeded
        - PaymentStatusOverpaid
        - PaymentStatusFailed
        - PaymentStatusRefunded
        - PaymentStatusPartiallyRefunded
        - PaymentStatusVoided
      x-speakeasy-name-override: PaymentStatus
    types.PaymentActionType:
      type: string
      enum:
        - checkout_url
        - payment_link
      x-enum-varnames:
        - PaymentActionTypeCheckoutURL
        - PaymentActionTypePaymentLink
      x-speakeasy-name-override: PaymentActionType
    types.AddAddonRef:
      type: object
      properties:
        addon_id:
          type: string
        association_id:
          type: string
        cadence:
          $ref: '#/components/schemas/types.AddonCadence'
        coupons:
          type: array
          items:
            $ref: '#/components/schemas/types.CouponRef'
        proration_behavior:
          $ref: '#/components/schemas/types.ProrationBehavior'
        start_date:
          type: string
          format: date-time
      x-speakeasy-name-override: AddAddonRef
    types.RemoveAddonRef:
      type: object
      properties:
        association_id:
          type: string
        effective_date:
          type: string
          format: date-time
        proration_behavior:
          $ref: '#/components/schemas/types.ProrationBehavior'
        reason:
          type: string
      x-speakeasy-name-override: RemoveAddonRef
    types.BillingPeriod:
      type: string
      enum:
        - MONTHLY
        - ANNUAL
        - WEEKLY
        - DAILY
        - QUARTERLY
        - HALF_YEARLY
        - ONETIME
      x-enum-varnames:
        - BILLING_PERIOD_MONTHLY
        - BILLING_PERIOD_ANNUAL
        - BILLING_PERIOD_WEEKLY
        - BILLING_PERIOD_DAILY
        - BILLING_PERIOD_QUARTER
        - BILLING_PERIOD_HALF_YEAR
        - BILLING_PERIOD_ONETIME
      x-speakeasy-name-override: BillingPeriod
    types.ModifySubscriptionLineItem:
      type: object
      properties:
        amount:
          type: string
        coupons:
          type: array
          items:
            $ref: '#/components/schemas/types.CouponRef'
        effective_date:
          type: string
          format: date-time
        line_item_id:
          type: string
        quantity:
          type: string
      x-speakeasy-name-override: ModifySubscriptionLineItem
    types.ModifySubscriptionType:
      type: string
      enum:
        - quantity_change
        - line_item_change
        - trial_end
      x-enum-varnames:
        - ModifySubscriptionTypeQuantityChange
        - ModifySubscriptionTypeLineItemChange
        - ModifySubscriptionTypeTrialEnd
      x-speakeasy-name-override: ModifySubscriptionType
    types.OnExistingEntityPolicy:
      type: string
      enum:
        - reject
        - supersede
      x-enum-varnames:
        - OnExistingEntityPolicyReject
        - OnExistingEntityPolicySupersede
      x-speakeasy-name-override: OnExistingEntityPolicy
    types.AddonCadence:
      type: string
      enum:
        - onetime
        - recurring
      x-enum-varnames:
        - AddonCadenceOnetime
        - AddonCadenceRecurring
      x-speakeasy-name-override: AddonCadence
    types.CouponRef:
      type: object
      properties:
        association_id:
          type: string
        coupon_id:
          type: string
        end_date:
          type: string
          format: date-time
        price_id:
          type: string
        start_date:
          type: string
          format: date-time
      x-speakeasy-name-override: CouponRef
    types.ProrationBehavior:
      type: string
      enum:
        - create_prorations
        - none
      x-enum-comments:
        ProrationBehaviorCreateProrations: 'Default: Create credits/charges on invoice'
        ProrationBehaviorNone: Calculate but don't apply (e.g., for previews)
      x-enum-varnames:
        - ProrationBehaviorCreateProrations
        - ProrationBehaviorNone
      x-speakeasy-name-override: ProrationBehavior
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      description: Enter your API key in the format *x-api-key &lt;api-key&gt;**
      name: x-api-key
      in: header

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.