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

# Create payment session

> Creates a hosted payment session. Resolves or creates the customer and returns an authenticated payment URL.



## OpenAPI

````yaml /openapi.yaml post /v1/payment-sessions
openapi: 3.0.3
info:
  title: Quentli REST API
  version: 1.0.0
  description: OpenAPI spec for Quentli REST endpoints.
servers:
  - url: https://api.quentli.com
    description: Production API
  - url: https://api.staging.quentli.com
    description: Staging API for production-like validation
  - url: https://api.demo.quentli.com
    description: Demo API hostname served by staging
security:
  - organizationApiKey: []
tags:
  - name: Auth
  - name: Billing
  - name: Catalog
  - name: Customers
  - name: Invoices
  - name: Payment Methods
  - name: Payment Sessions
  - name: Payments
  - name: Subscriptions
  - name: Tax Invoices
  - name: Webhooks
paths:
  /v1/payment-sessions:
    post:
      tags:
        - Payment Sessions
      summary: Create payment session
      description: >-
        Creates a hosted payment session. Resolves or creates the customer and
        returns an authenticated payment URL.
      operationId: payment_sessions_create
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePaymentSessionArgs'
      responses:
        '200':
          description: Payment session created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePaymentSessionPayload'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserError'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserError'
        '403':
          description: Permission denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserError'
components:
  schemas:
    CreatePaymentSessionArgs:
      type: object
      properties:
        input:
          type: object
          properties:
            returnUrl:
              type: string
              description: URL to redirect to after successful payment.
              example: https://example.com/success
            cancelUrl:
              type: string
              description: URL to redirect to if the payer cancels.
              example: https://example.com/cancel
            displayMode:
              type: string
              enum:
                - CUSTOMER_PORTAL
                - CUSTOM
                - EMBEDDED
              default: CUSTOMER_PORTAL
              description: How the payment UI is presented.
              example: CUSTOMER_PORTAL
            expiresAt:
              anyOf:
                - type: string
                  description: Date string
                - type: string
                  format: date-time
                  description: Date object
              description: Optional expiration time for the session.
            customer:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  description: Customer full name.
                  example: Juan Pérez
                externalId:
                  type: string
                  description: External ID used to match or create the customer.
                  example: A-1029
                phoneNumber:
                  type: string
                  description: Customer phone number in E.164 format.
                  example: '+5215512345678'
                email:
                  type: string
                  format: email
                  description: Customer email address.
                  example: juan@example.com
                forceUpdate:
                  type: boolean
                  description: >-
                    Whether to treat the provided customer contact fields as
                    authoritative. If another customer in the organization has
                    the provided email or phone number, that field is unset from
                    the other customer and set on the resolved customer.
                  example: false
                metadata:
                  type: array
                  items:
                    type: object
                    properties:
                      key:
                        type: string
                      value:
                        type: string
                    required:
                      - key
                      - value
                  description: Metadata entries to attach to the customer.
                  example: []
              required:
                - name
              additionalProperties: false
            description:
              type: string
              description: Payment description (used when items are not provided).
              example: Colegiatura Enero 2025
            amount:
              type: number
              minimum: 1
              description: >-
                Total amount in minor currency units (used when items are not
                provided).
              example: 150000
            currency:
              type: string
              description: ISO 4217 currency code (used when items are not provided).
              example: MXN
            items:
              type: array
              items:
                type: object
                properties:
                  description:
                    type: string
                    description: Line item description.
                    example: Colegiatura
                  quantity:
                    type: number
                    minimum: 1
                    description: Quantity of units.
                    example: 1
                  amount:
                    type: number
                    minimum: 1
                    description: Unit price in minor currency units.
                    example: 150000
                  currency:
                    type: string
                    description: ISO 4217 currency code.
                    example: MXN
                required:
                  - description
                  - quantity
                  - amount
                  - currency
                additionalProperties: false
              description: >-
                Line items to include in the session. Overrides
                amount/currency/description if provided.
              example: []
            metadata:
              type: array
              items:
                type: object
                properties:
                  key:
                    type: string
                  value:
                    type: string
                required:
                  - key
                  - value
                additionalProperties: false
              description: Metadata entries to attach to the session.
              example: []
          required:
            - customer
          additionalProperties: false
      required:
        - input
      description: Request body for creating a payment session.
    CreatePaymentSessionPayload:
      type: object
      properties:
        url:
          type: string
          description: Authenticated payment URL for the customer.
        session:
          type: object
          properties:
            accessToken:
              type: string
              description: JWT access token.
            csrfToken:
              type: string
              description: CSRF token for form submissions.
            refreshToken:
              type: string
              description: Token used to obtain a new access token.
            accessTokenExpiresAt:
              anyOf:
                - type: string
                  description: Date string
                - type: string
                  format: date-time
                  description: Date object
              description: When the access token expires.
            expiresAt:
              anyOf:
                - type: string
                  description: Date string
                - type: string
                  format: date-time
                  description: Date object
              description: When the session expires entirely.
          required:
            - accessToken
            - csrfToken
            - refreshToken
            - accessTokenExpiresAt
            - expiresAt
          description: Customer session tokens, if a customer was resolved.
        paymentSession:
          type: object
          properties:
            id:
              type: string
              description: Unique identifier of the payment session.
              example: ps_1234567890abcdefghij
            createdAt:
              type: string
              format: date-time
              description: When the session was created.
              example: '2025-01-15T18:00:00.000Z'
            updatedAt:
              type: string
              format: date-time
              description: When the session was last updated.
              example: '2025-01-15T18:00:00.000Z'
            status:
              type: string
              enum:
                - PENDING
                - FINALIZED
                - CANCELED
                - EXPIRED
              description: Current session status.
              example: PENDING
            displayMode:
              type: string
              enum:
                - CUSTOMER_PORTAL
                - CUSTOM
                - EMBEDDED
              description: How the payment UI is presented.
              example: CUSTOMER_PORTAL
            origin:
              type: string
              enum:
                - API
                - INVOICE
                - LISTING
              description: How the session was created.
              example: API
            expiresAt:
              anyOf:
                - type: string
                  description: Date string
                - type: string
                  format: date-time
                  description: Date object
                - nullable: true
              description: Optional expiration date of the session.
              example: null
            totalAmount:
              type: number
              description: Total amount in minor currency units.
              example: 150000
            currency:
              type: string
              description: ISO 4217 currency code.
              example: MXN
            customerId:
              type: string
              nullable: true
              description: Identifier of the customer associated with the session, if any.
              example: null
            returnUrl:
              type: string
              nullable: true
              description: URL to redirect to after successful payment.
              example: null
            cancelUrl:
              type: string
              nullable: true
              description: URL to redirect to if the payer cancels.
              example: null
            organizationId:
              type: string
              description: Identifier of the owning organization.
              example: org_1234567890abcdefghij
            items:
              type: array
              items:
                $ref: '#/components/schemas/PaymentSessionItem'
              description: Line items in the session.
            customer:
              allOf:
                - $ref: '#/components/schemas/Customer'
                - nullable: true
              description: Customer associated with the session, if any.
            metadata:
              type: array
              items:
                type: object
                properties:
                  key:
                    type: string
                  value:
                    type: string
                required:
                  - key
                  - value
                additionalProperties: false
              nullable: true
              description: Session-level metadata entries.
          required:
            - id
            - createdAt
            - updatedAt
            - status
            - displayMode
            - origin
            - expiresAt
            - totalAmount
            - currency
            - customerId
            - returnUrl
            - cancelUrl
            - organizationId
            - items
            - customer
            - metadata
          description: The created payment session.
      required:
        - url
        - paymentSession
      additionalProperties: false
      description: Created payment session with an authenticated URL.
    UserError:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
          required:
            - message
      required:
        - error
      additionalProperties: false
      description: Standard user-facing error response envelope.
    PaymentSessionItem:
      type: object
      properties:
        description:
          type: string
          description: Line item description.
          example: Colegiatura Enero 2025
        amount:
          type: number
          description: Unit price in minor currency units.
          example: 150000
        quantity:
          type: number
          description: Quantity of units.
          example: 1
        currency:
          type: string
          description: ISO 4217 currency code.
          example: MXN
      required:
        - description
        - amount
        - quantity
        - currency
      description: A line item within a payment session.
    Customer:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the customer.
          example: cus_1234567890abcdefghij
        createdAt:
          anyOf:
            - type: string
              description: Date string
            - type: string
              format: date-time
              description: Date object
          description: Date and time when the customer was created.
          example: '2025-01-10T12:00:00.000Z'
        updatedAt:
          anyOf:
            - type: string
              description: Date string
            - type: string
              format: date-time
              description: Date object
          description: Date and time when the customer was last updated.
          example: '2025-01-10T12:00:00.000Z'
        name:
          type: string
          description: Name of the customer.
          example: Juan Pérez
        username:
          type: string
          description: Username used for customer login and customer identification.
          example: juan_perez_01
        email:
          type: string
          nullable: true
          description: Email address of the customer.
          example: juan@example.com
        phoneNumber:
          type: string
          nullable: true
          description: >-
            Primary WhatsApp phone number of the customer, usually in E.164
            format.
          example: '+525512345678'
        organizationId:
          type: string
          description: Identifier of the organization this customer belongs to.
          example: org_1234567890abcdefghij
        secondaryPhoneNumber:
          type: string
          nullable: true
          description: Secondary phone number used for reminders and announcements.
          example: null
        archivedAt:
          anyOf:
            - type: string
              description: Date string
            - type: string
              format: date-time
              description: Date object
            - nullable: true
          description: Date and time when the customer was archived.
          example: null
        archivedById:
          type: string
          nullable: true
          description: Identifier of the user who archived this customer.
          example: u_1234567890abcdefghij
        acceptedServiceAgreement:
          type: boolean
          description: Whether the customer has accepted the service agreement.
          example: true
        skipTaxInvoice:
          type: boolean
          description: Whether tax invoice generation is skipped for this customer.
          example: false
        emailVerified:
          type: boolean
          description: Whether the customer has verified their email address.
          example: false
        phoneNumberVerified:
          type: boolean
          description: Whether the customer has verified their phone number.
          example: true
        hasChangedPassword:
          type: boolean
          description: Whether the customer has set a non-default password.
          example: true
        signatureAcceptedAt:
          anyOf:
            - type: string
              description: Date string
            - type: string
              format: date-time
              description: Date object
            - nullable: true
          description: >-
            Date and time when recurring charges terms were accepted via
            signature.
          example: '2025-01-10T12:00:00.000Z'
        optedOutWhatsappAt:
          anyOf:
            - type: string
              description: Date string
            - type: string
              format: date-time
              description: Date object
            - nullable: true
          description: Date and time when the customer opted out of WhatsApp reminders.
          example: null
        optedInWhatsappAt:
          anyOf:
            - type: string
              description: Date string
            - type: string
              format: date-time
              description: Date object
            - nullable: true
          description: Date and time when the customer opted in to WhatsApp reminders.
          example: '2025-01-05T10:00:00.000Z'
        startedWhatsappAt:
          anyOf:
            - type: string
              description: Date string
            - type: string
              format: date-time
              description: Date object
            - nullable: true
          description: >-
            Date and time when WhatsApp opt-in flow was started for this
            customer.
          example: '2025-01-05T09:55:00.000Z'
        replyWithAssistant:
          type: boolean
          nullable: true
          description: Whether to reply to this customer using the assistant.
          example: false
        metadata:
          type: array
          nullable: true
          items:
            type: object
            properties:
              key:
                type: string
              value:
                type: string
            required:
              - key
              - value
            additionalProperties: false
          description: >-
            Custom metadata entries attached to this customer as key-value
            pairs.
          example:
            - key: studentId
              value: A-1029
        meta:
          type: object
          nullable: true
          additionalProperties:
            type: string
          description: Flattened metadata map where each key maps to a string value.
          example:
            studentId: A-1029
      required:
        - id
        - createdAt
        - updatedAt
        - name
        - username
        - email
        - phoneNumber
        - organizationId
        - secondaryPhoneNumber
        - archivedAt
        - archivedById
        - acceptedServiceAgreement
        - skipTaxInvoice
        - emailVerified
        - phoneNumberVerified
        - hasChangedPassword
        - signatureAcceptedAt
        - optedOutWhatsappAt
        - optedInWhatsappAt
        - startedWhatsappAt
        - replyWithAssistant
      description: >-
        Customer record including identity, contact details, and messaging
        preferences.
  securitySchemes:
    organizationApiKey:
      type: http
      scheme: bearer
      description: 'Organization API key using `Authorization: Bearer sk_...`.'

````