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

# Create a payment intent

> Creates a new payment intent for a customer to purchase a plan, top up credits (`purpose: "credit_topup"`), or bill usage (`purpose: "usage_billing"`) with an explicit `amount`/`currency`. Requires an idempotency key to prevent duplicate charges. Returns client secret and publishable key needed for frontend integration.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/sdk/payment-intents
openapi: 3.0.0
info:
  contact: {}
  description: The SolvaPay REST API specification
  title: SolvaPay REST API
  version: '1.0'
servers: []
security: []
tags: []
paths:
  /v1/sdk/payment-intents:
    post:
      tags:
        - Payment Intents
      summary: Create a payment intent
      description: >-
        Creates a new payment intent for a customer to purchase a plan, top up
        credits (`purpose: "credit_topup"`), or bill usage (`purpose:
        "usage_billing"`) with an explicit `amount`/`currency`. Requires an
        idempotency key to prevent duplicate charges. Returns client secret and
        publishable key needed for frontend integration.
      operationId: PaymentIntentSdkController_createPaymentIntent
      parameters:
        - description: Unique idempotency key to prevent duplicate payments (required)
          in: header
          name: idempotency-key
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePaymentIntentDto'
        description: Payment intent creation data
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SdkPaymentIntentResponse'
          description: Payment intent created successfully
        '400':
          content:
            application/json:
              schema:
                example:
                  error: Bad Request
                  message: idempotency-key header is required
                  statusCode: 400
          description: Missing required fields or invalid data
      security:
        - SecretKey: []
components:
  schemas:
    CreatePaymentIntentDto:
      properties:
        amount:
          exclusiveMaximum: false
          exclusiveMinimum: false
          maximum: 10000000
          minimum: 100
          type: integer
        autoRecharge:
          properties:
            currency:
              type: string
            enabled:
              type: boolean
            maxMonthlySpendMajor:
              exclusiveMaximum: false
              exclusiveMinimum: true
              maximum: 10000
              minimum: 0
              type: number
            thresholdAmountMajor:
              exclusiveMaximum: false
              exclusiveMinimum: true
              maximum: 10000
              minimum: 0
              type: number
            topupAmountMajor:
              exclusiveMaximum: false
              exclusiveMinimum: true
              maximum: 10000
              minimum: 0
              type: number
            triggerType:
              enum:
                - balance
              type: string
          type: object
        currency:
          type: string
        customerRef:
          maxLength: 20
          minLength: 1
          type: string
        description:
          maxLength: 500
          type: string
        planRef:
          maxLength: 20
          minLength: 1
          type: string
        pricingTier:
          type: string
        productRef:
          maxLength: 20
          minLength: 1
          type: string
        purpose:
          default: product
          enum:
            - product
            - credit_topup
            - usage_billing
          type: string
      required:
        - customerRef
      type: object
    SdkPaymentIntentResponse:
      properties:
        accountId:
          description: Connected Stripe account ID (only present on create)
          example: acct_1A2B3C4D
          type: string
        amount:
          description: >-
            Amount in USD minor units (ledger/normalised). The charge-currency
            amount is `originalAmount` paired with `currency`.
          example: 4999
          type: number
        clientSecret:
          description: Client secret used to confirm the payment on the client
          example: pi_1a2b3c4d5e6f7g8h_secret_AbCdEf123456
          type: string
        createdAt:
          description: Creation timestamp
          example: '2025-10-18T10:30:00.000Z'
          type: string
        currency:
          description: >-
            ISO 4217 presentment (charge) currency code — pairs with
            `originalAmount`
          example: usd
          type: string
        customerRef:
          description: Customer reference
          example: cus_3c4d5e6f7g8h
          type: string
        exchangeRate:
          description: Exchange rate applied to convert to USD
          example: 1
          type: number
        expiresAt:
          description: Expiry timestamp of the payment intent
          example: '2025-10-19T10:30:00.000Z'
          type: string
        originalAmount:
          description: >-
            Charge-currency amount in minor units (the currency the customer is
            billed in)
          example: 4999
          type: number
        planRef:
          description: Plan reference
          example: pln_2b3c4d5e6f7g
          type: string
        processorPaymentId:
          description: Payment processor payment intent ID
          example: pi_1a2b3c4d5e6f7g8h
          type: string
        publishableKey:
          description: Stripe publishable key for the environment
          example: pk_test_...
          type: string
        status:
          description: Payment intent status
          enum:
            - pending
            - requires_payment_method
            - requires_confirmation
            - requires_action
            - processing
            - succeeded
            - failed
            - cancelled
          example: requires_payment_method
          type: string
        transactionId:
          description: Ledger transaction ID
          example: 507f1f77bcf86cd799439011
          type: string
      required:
        - processorPaymentId
        - amount
        - currency
        - status
        - clientSecret
        - publishableKey
      type: object
  securitySchemes:
    SecretKey:
      bearerFormat: JWT
      description: >-
        Provider secret API key (sk_live_… / sk_test_…) supplied as a Bearer
        token.
      scheme: bearer
      type: http

````