{
  "slug": "payment-intents-add-card-not-present-surcharge-fields-d1c2f0c4b520",
  "title": "Payment Intents add card-not-present surcharge fields",
  "tools": [
    "stripe"
  ],
  "tags": [
    "agent"
  ],
  "introduced_at": "2026-03-25T00:00:00.000Z",
  "announced_at": "2026-03-25T00:00:00.000Z",
  "effective_at": null,
  "date_basis": "source-publication",
  "status": "unknown",
  "how": {
    "incantation": "For card-not-present PaymentIntents with a surcharge, include the surcharge in the total `amount` and provide `amount_details.surcharge.amount` when creating, updating, confirming, or capturing. Configure `amount_details.surcharge.enforce_validation` as `automatic`, `enabled`, or `disabled`; `automatic` is the default and changeable, while `enabled` and `disabled` cannot be changed.",
    "examples": [
      "curl https://api.stripe.com/v1/payment_intents \\\n  -u \"<<YOUR_SECRET_KEY>>\" \\\n  -H \"Stripe-Version: 2026-03-25.preview\" \\\n  -d amount=<TOTAL_AMOUNT_IN_SMALLEST_CURRENCY_UNIT> \\\n  -d currency=<CURRENCY> \\\n  -d \"amount_details[surcharge][amount]=<SURCHARGE_AMOUNT>\" \\\n  -d \"amount_details[surcharge][enforce_validation]=automatic\"",
      "curl https://api.stripe.com/v1/payment_intents/<PAYMENT_INTENT_ID> \\\n  -u \"<<YOUR_SECRET_KEY>>\" \\\n  -H \"Stripe-Version: 2026-03-25.preview\" \\\n  -d amount=<TOTAL_AMOUNT_IN_SMALLEST_CURRENCY_UNIT> \\\n  -d \"amount_details[surcharge][amount]=<SURCHARGE_AMOUNT>\" \\\n  -d \"amount_details[surcharge][enforce_validation]=automatic\"",
      "curl https://api.stripe.com/v1/payment_intents/<PAYMENT_INTENT_ID>/confirm \\\n  -u \"<<YOUR_SECRET_KEY>>\" \\\n  -H \"Stripe-Version: 2026-03-25.preview\" \\\n  -d amount=<TOTAL_AMOUNT_IN_SMALLEST_CURRENCY_UNIT> \\\n  -d \"amount_details[surcharge][amount]=<SURCHARGE_AMOUNT>\" \\\n  -d \"amount_details[surcharge][enforce_validation]=automatic\""
    ],
    "gotchas": [
      "Version: 2026-03-25.preview",
      "Availability: Preview API version 2026-03-25.preview",
      "amount (required): Total amount, inclusive of the surcharge, in the smallest currency unit.",
      "amount_details.surcharge.amount (required): Identifies the surcharge amount.",
      "amount_details.surcharge.enforce_validation: Validation enforcement setting; `automatic` is the default and changeable, while `enabled` and `disabled` cannot be changed.",
      "amount_details.surcharge.enforce_validation=automatic: Enforces validation; can be changed.",
      "amount_details.surcharge.enforce_validation=enabled: Enforces validation; cannot be changed.",
      "amount_details.surcharge.enforce_validation=disabled: Does not enforce validation; cannot be changed.",
      "Prerequisite: Use Stripe API version `2026-03-25.preview`; requests require a secret key in the documented curl examples.",
      "If `amount_details.surcharge.enforce_validation` is `enabled` or `disabled`, it cannot be changed.",
      "If `amount_details.surcharge.enforce_validation` is `automatic`, validation is enforced but the setting can be changed.",
      "Pass the total amount inclusive of the surcharge when creating, updating, confirming, or capturing a Payment Intent with a surcharge."
    ]
  },
  "why_it_matters": "Update a Payment Intents integration to create, update, confirm, or capture card-not-present payments with a surcharge.",
  "before": "Calculate the surcharge separately from the Payment Intent total.",
  "sources": [
    "https://docs.stripe.com/changelog/dahlia/2026-03-25/card-not-present-payments-surcharge-configuration-options",
    "https://docs.stripe.com/api/payment_intents/create?api-version=2026-03-25.preview",
    "https://docs.stripe.com/api/payment_intents/update?api-version=2026-03-25.preview",
    "https://docs.stripe.com/api/payment_intents/confirm?api-version=2026-03-25.preview",
    "https://docs.stripe.com/api/payment_intents/object?api-version=2026-03-25.preview#payment_intent_object-amount_details-surcharge-amount",
    "https://docs.stripe.com/api/payment_intents/create?api-version=2026-03-25.preview#create_payment_intent-amount_details-surcharge-enforce_validation"
  ],
  "rank": 0.95027,
  "judge": {
    "publish": true,
    "judge_model": "codex-cli/gpt-6-luna+typesafe/jev-1.13.0",
    "prompt_version": "extract-v7+enrich-v2+judge-v2x3+jev-publish-v1"
  },
  "review_state": "approved",
  "provenance": {
    "run_id": "wave1b-tools-20261017",
    "verdict_id": "wave1b-tools-20261017:wave1b-tools-20261017-87e4f933451e1024-0:gate",
    "evidence_hash": "b24c9aba83cc9875fcd0783fec84867704779a268689632397f28786be483d2c"
  },
  "review": {
    "draft_hash": "43585532526f608a4c5a882d7247869019688c1eed83e337128e849535316e99",
    "reviewer": "publication-gate",
    "reviewed_at": "2026-10-07T00:00:00.000Z",
    "decision": "wave1b-tools-20261017:gate",
    "reason": "2 of 3 judge runs approved with p_yes >= 0.9 (mean 0.95 >= 0.9; 2 needed) and Jev gave 0.64 (>= 0.6 needed)."
  }
}