fulcrum: "1.0"
name: stripe_create_payment_intent
description: Create a Stripe PaymentIntent to collect a payment — the recommended modern way to accept payments (replaces the legacy Charges API)

schema:
  input:
    type: object
    properties:
      amount:
        type: integer
        description: "Amount in the smallest currency unit (e.g. cents for USD). Example: 2000 = $20.00"
        minimum: 1
      currency:
        type: string
        description: "Three-letter ISO 4217 currency code (e.g. 'usd', 'eur', 'gbp')"
        examples: [usd, eur, gbp, jpy]
      customer:
        type: string
        description: "Stripe customer ID (cus_...) to attach the payment intent to"
      description:
        type: string
        description: "Arbitrary description (shown in dashboard and on receipts)"
      receipt_email:
        type: string
        description: "Email address to send a receipt to on successful payment"
      payment_method:
        type: string
        description: "Payment method ID (pm_...) to attach immediately"
      confirm:
        type: boolean
        description: "If true, attempt to confirm the payment immediately after creation (requires payment_method)"
        default: false
      automatic_payment_methods:
        type: boolean
        description: "Enable Stripe's automatic payment methods (recommended for new integrations)"
        default: true
      metadata:
        type: object
        description: "Arbitrary key-value pairs for your own bookkeeping (max 50 keys, 500 chars/value)"
      setup_future_usage:
        type: string
        description: "Indicate future usage: 'off_session' or 'on_session' to save payment method"
        enum: [off_session, on_session]
    required:
      - amount
      - currency
  output:
    type: object
    properties:
      id:
        type: string
        description: "PaymentIntent ID (pi_...)"
      client_secret:
        type: string
        description: "Client secret for client-side payment confirmation"
      status:
        type: string
        description: "Payment status"
        enum: [requires_payment_method, requires_confirmation, requires_action, processing, requires_capture, canceled, succeeded]
      amount:
        type: integer
      currency:
        type: string
      created:
        type: integer
        description: Unix timestamp of creation
      customer:
        type: string
      description:
        type: string
      payment_method:
        type: string
      object:
        type: string
        enum: [payment_intent]

providers:
  primary:
    service: rest
    cost_per_call: 0
    timeout: 15
    config:
      base_url: https://api.stripe.com
      path: /v1/payment_intents
      method: POST
      headers:
        Authorization: "Bearer {env.STRIPE_SECRET_KEY}"
        Content-Type: "application/x-www-form-urlencoded"
      params:
        amount: "{amount}"
        currency: "{currency}"
        customer: "{customer}"
        description: "{description}"
        receipt_email: "{receipt_email}"
        payment_method: "{payment_method}"
        confirm: "{confirm}"

cache:
  strategy: none
  ttl: 0

auth:
  required: true
  type: bearer
  key: env:STRIPE_SECRET_KEY
  description: "Get your secret key from https://dashboard.stripe.com/apikeys. Use test keys (sk_test_...) for development and live keys (sk_live_...) in production."
  header: Authorization
  prefix: Bearer

metadata:
  category: finance
  tags:
    - stripe
    - payments
    - payment-intent
    - finance
    - billing
    - checkout
  cost_category: free
  execution_time: fast
  read_only: false
  rate_limit: "100 req/sec"
  docs: https://stripe.com/docs/api/payment_intents/create
