Stripe调用手册

创建并查询测试 PaymentIntent

建立一笔未确认的测试支付意图,记录金额、币种和状态,再查询同一个资源。

官方资料核对 2026-10-15示例代码,未进行真实接口实测
← 返回平台功能

接入准备

  • 注册 Stripe,在 Dashboard 切换到沙盒或测试环境,取得当前环境的服务端测试 Key。
  • 运行示例前核对密钥前缀为 sk_test_;发布正式收款另需支持地区与账户业务审核,本手册不完成激活。

准备环境变量

示例值需要替换为自己的凭证或资源 ID。代码在本机或服务端运行;密钥不应放进公开网页。

STRIPE_TEST_SECRET_KEY
Dashboard 当前测试环境的服务端 sk_test_ 密钥,禁止使用 sk_live_。
STRIPE_PAYMENT_INTENT_ID
第一步响应 id,复制后再运行查询代码。
STRIPE_IDEMPOTENCY_KEY可选
可选;同一次创建操作的重试必须沿用;新业务操作使用新值。
终端
export STRIPE_TEST_SECRET_KEY='sk_test_replace_with_your_key'
export STRIPE_PAYMENT_INTENT_ID='pi_ExampleTestIntent'
# 可选,按需启用
# export STRIPE_IDEMPOTENCY_KEY='demo_unique_operation_key'

以上 export 适用于 macOS / Linux 的终端,在同一终端内运行后续代码。Python 示例保存为 request.py 后执行 python3 request.py。

调用步骤

  1. 01

    在 Dashboard 当前测试环境的 Developers / API keys 中复制 Secret key,在自己服务端设置 STRIPE_TEST_SECRET_KEY。

  2. 02

    保存下面的 Python 示例为文件并使用 Python 3 运行;示例仅用标准库,会拒绝非 sk_test_ 密钥。

  3. 03

    先创建未确认的 PaymentIntent,再从响应中复制 id 查询状态;不要把 client_secret 写入日志或公开 URL。

调用 01

创建未确认支付意图

2000 表示 20.00 USD,以最小货币单位计;本例仅允许 card 且不附加支付方式、不传 confirm。

POSThttps://api.stripe.com/v1/payment_intents

请求头

Authorization
Bearer ${STRIPE_TEST_SECRET_KEY}
Accept
application/json
Content-Type
application/x-www-form-urlencoded

参数说明

参数表可左右滑动,查看完整说明。

字段 / 位置类型 / 必填说明
amount请求体integer必填金额的最小货币单位,示例 USD 2000 = 20 美元;不同货币小数位不同。
currency请求体string必填三字母小写币种,示例 usd。
payment_method_types[]请求体string[]可选示例仅使用 card;form 参数名保留方括号。
Idempotency-KeyHeaderstring可选由自己服务端生成;重试同一创建时保持键与参数不变。

调用代码

替换示例 ID 与请求体内容后运行。

Python 3
import json, os, uuid, urllib.parse, urllib.request, urllib.error
key = os.environ["STRIPE_TEST_SECRET_KEY"]
if not key.startswith("sk_test_"):
    raise SystemExit("本示例只接受 sk_test_ 测试密钥")
# 首次调用生成一个键;网络重试同一操作时沿用该键和完全相同的参数。
idempotency_key = os.environ.get("STRIPE_IDEMPOTENCY_KEY") or "demo-" + str(uuid.uuid4())
print("本次幂等键(重试时设置 STRIPE_IDEMPOTENCY_KEY):", idempotency_key)
body = urllib.parse.urlencode({"amount": 2000, "currency": "usd", "payment_method_types[]": "card"}).encode()
req = urllib.request.Request("https://api.stripe.com/v1/payment_intents", data=body, method="POST", headers={
    "Authorization": "Bearer " + key,
    "Content-Type": "application/x-www-form-urlencoded",
    "Idempotency-Key": idempotency_key,
})
try:
    with urllib.request.urlopen(req, timeout=30) as response:
        data = json.load(response)
except urllib.error.HTTPError as exc:
    raise SystemExit(f"HTTP {exc.code}: {exc.read().decode()}")
# 不打印 client_secret。
print(json.dumps({name: data.get(name) for name in ("id", "amount", "currency", "status", "livemode")}, indent=2))
if data.get("livemode") is not False:
    raise SystemExit("环境核对失败,请停止继续处理")

返回示例

按官方结构整理的节选示意,非实测结果。保存 id 供第二步使用;status 为 requires_payment_method 表示尚未提供付款方式;创建成功不等于支付成功。 以下为结构示意,非本站实测结果。

JSON
{
  "id": "pi_ExampleTestIntent",
  "object": "payment_intent",
  "amount": 2000,
  "currency": "usd",
  "status": "requires_payment_method",
  "livemode": false
}

常见错误与排查

HTTP 401API Key 无效或认证失败
确认环境变量包含 Secret key,未误用 pk_test_ 公钥或已撤销密钥。
HTTP 400参数或幂等键使用不正确
查看 error.type、error.code、error.param 与 message;同一幂等键不能用于不同参数。
HTTP 404该环境找不到资源
确认资源 ID 与当前测试环境及账户一致。

调用注意

  • Stripe 此端点接收 form 编码,不是直接发送 JSON;本页只提供完整 Python 版本。
调用 02

查询刚创建的支付意图

把 STRIPE_PAYMENT_INTENT_ID 设置为第一步返回的 id;这一步只读取,不确认或扣款。

GEThttps://api.stripe.com/v1/payment_intents/${STRIPE_PAYMENT_INTENT_ID}

请求头

Authorization
Bearer ${STRIPE_TEST_SECRET_KEY}
Accept
application/json

参数说明

参数表可左右滑动,查看完整说明。

字段 / 位置类型 / 必填说明
intentPathstring必填第一步返回的 pi_ 开头 ID,必须属于同一测试环境。

调用代码

替换示例 ID 与请求体内容后运行。

Python 3
import json, os, re, urllib.request, urllib.error
key = os.environ["STRIPE_TEST_SECRET_KEY"]
if not key.startswith("sk_test_"):
    raise SystemExit("本示例只接受 sk_test_ 测试密钥")
intent_id = os.environ["STRIPE_PAYMENT_INTENT_ID"]
if not re.fullmatch(r"pi_[A-Za-z0-9]+", intent_id):
    raise SystemExit("请输入上一请求返回的 pi_ ID")
req = urllib.request.Request("https://api.stripe.com/v1/payment_intents/" + intent_id,
    headers={"Authorization": "Bearer " + key})
try:
    with urllib.request.urlopen(req, timeout=30) as response:
        data = json.load(response)
except urllib.error.HTTPError as exc:
    raise SystemExit(f"HTTP {exc.code}: {exc.read().decode()}")
print(json.dumps({name: data.get(name) for name in ("id", "amount", "amount_received", "currency", "status", "livemode")}, indent=2))
if data.get("livemode") is not False:
    raise SystemExit("环境核对失败")

返回示例

按官方结构整理的节选示意,非实测结果。status 是支付生命周期状态;amount_received 是已收到的金额,本示例为 0。生产履约还需可信事件与业务核验。 以下为结构示意,非本站实测结果。

JSON
{
  "id": "pi_ExampleTestIntent",
  "amount": 2000,
  "amount_received": 0,
  "currency": "usd",
  "status": "requires_payment_method",
  "livemode": false
}

常见错误与排查

HTTP 401API Key 无效或认证失败
确认环境变量包含 Secret key,未误用 pk_test_ 公钥或已撤销密钥。
HTTP 400参数或幂等键使用不正确
查看 error.type、error.code、error.param 与 message;同一幂等键不能用于不同参数。
HTTP 404该环境找不到资源
确认资源 ID 与当前测试环境及账户一致。

调用注意

  • 代码仅打印必要字段,避免把 client_secret 一并输出。

注意事项

  • 沙盒不会转移真实资金;本例不确认 PaymentIntent,不产生正式扣款。测试对象不能与 live 对象混用。
  • 正式支付价格因账户地区和支付方式不同;测试成功不能证明正式收款资格、费率或结算已获批准。

核验来源

本站按官方资料整理本场景的必要调用步骤与代码,覆盖范围以本页列出的接口为准。官方资料用于追溯规范及查看变更。

  1. 01
  2. 02
    Stripe 沙盒与测试数据核验日期 2026-10-15
  3. 03
    创建 PaymentIntent核验日期 2026-10-15
  4. 04
    Stripe 幂等请求核验日期 2026-10-15
  5. 05
    Stripe 错误结构核验日期 2026-10-15
  6. 06
    读取 PaymentIntent核验日期 2026-10-15

Stripe的其他调用手册

← 返回Stripe的全部功能