创建并查询测试 PaymentIntent
建立一笔未确认的测试支付意图,记录金额、币种和状态,再查询同一个资源。
← 返回平台功能接入准备
- 注册 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。
调用步骤
- 01
在 Dashboard 当前测试环境的 Developers / API keys 中复制 Secret key,在自己服务端设置 STRIPE_TEST_SECRET_KEY。
- 02
保存下面的 Python 示例为文件并使用 Python 3 运行;示例仅用标准库,会拒绝非 sk_test_ 密钥。
- 03
先创建未确认的 PaymentIntent,再从响应中复制 id 查询状态;不要把 client_secret 写入日志或公开 URL。
创建未确认支付意图
2000 表示 20.00 USD,以最小货币单位计;本例仅允许 card 且不附加支付方式、不传 confirm。
https://api.stripe.com/v1/payment_intents请求头
AuthorizationBearer ${STRIPE_TEST_SECRET_KEY}Acceptapplication/jsonContent-Typeapplication/x-www-form-urlencoded
参数说明
参数表可左右滑动,查看完整说明。
| 字段 / 位置 | 类型 / 必填 | 说明 |
|---|---|---|
amount请求体 | integer必填 | 金额的最小货币单位,示例 USD 2000 = 20 美元;不同货币小数位不同。 |
currency请求体 | string必填 | 三字母小写币种,示例 usd。 |
payment_method_types[]请求体 | string[]可选 | 示例仅使用 card;form 参数名保留方括号。 |
Idempotency-KeyHeader | string可选 | 由自己服务端生成;重试同一创建时保持键与参数不变。 |
调用代码
替换示例 ID 与请求体内容后运行。
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 表示尚未提供付款方式;创建成功不等于支付成功。 以下为结构示意,非本站实测结果。
{
"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 版本。
查询刚创建的支付意图
把 STRIPE_PAYMENT_INTENT_ID 设置为第一步返回的 id;这一步只读取,不确认或扣款。
https://api.stripe.com/v1/payment_intents/${STRIPE_PAYMENT_INTENT_ID}请求头
AuthorizationBearer ${STRIPE_TEST_SECRET_KEY}Acceptapplication/json
参数说明
参数表可左右滑动,查看完整说明。
| 字段 / 位置 | 类型 / 必填 | 说明 |
|---|---|---|
intentPath | string必填 | 第一步返回的 pi_ 开头 ID,必须属于同一测试环境。 |
调用代码
替换示例 ID 与请求体内容后运行。
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。生产履约还需可信事件与业务核验。 以下为结构示意,非本站实测结果。
{
"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 对象混用。
- 正式支付价格因账户地区和支付方式不同;测试成功不能证明正式收款资格、费率或结算已获批准。
核验来源
本站按官方资料整理本场景的必要调用步骤与代码,覆盖范围以本页列出的接口为准。官方资料用于追溯规范及查看变更。
- 01Stripe API Key 与测试环境隔离核验日期 2026-10-15
- 02Stripe 沙盒与测试数据核验日期 2026-10-15
- 03创建 PaymentIntent核验日期 2026-10-15
- 04Stripe 幂等请求核验日期 2026-10-15
- 05Stripe 错误结构核验日期 2026-10-15
- 06读取 PaymentIntent核验日期 2026-10-15