支付意向 API 功能

列出所有支付意向

返回支付意向的列表。

端点：https://api.stripe.com/v1/payment_intents

操作：GET

示例

cURL 示例：

curl -X GET https://api.stripe.com/v1/payment_intents \
  -u <YOUR_SECRET_KEY>:

响应

响应将返回标准代码。

200: OK

{
  "object": "list",
  "data": [
    {
      "id": "pi_1234567890",
      "object": "payment_intent",
      "amount": 1000,
      "currency": "usd",
      "status": "requires_confirmation"
    }
  ],
  "has_more": false,
  "url": "/v1/payment_intents"
}

400: Bad Request

{
  "error": {
    "message": "If passing an array with explicit keys (e.g. foo[0]=a&foo[1]=b) instead of as an array (e.g. foo[]=a&foo[]=b), the keys must be numeric and sequential starting from 0. You passed the keys `1`, we expected to have a key with the value `0`.",
    "param": "expand",
    "request_log_url": "https://dashboard.stripe.com/test/logs/req_kCeAL5FAly5bkh?t=1734734555",
    "type": "invalid_request_error"
  }
}

401: Unauthorized

{
  "error": {
    "type": "invalid_request_error",
    "message": "Invalid API Key provided: sk_test_********************1234"
  }
}

参数

查询参数

参数	类型	描述
limit	整数	返回对象数量的限制。限制范围为 1 到 100，默认值为 10。
starting_after	字符串	分页时使用的游标。starting_after 是一个对象 ID，用于定义您在列表中的位置。
ending_before	字符串	分页所用的游标。ending_before 是一个对象 ID，用于定义您在列表中的位置。
expand[]	字符串数组	指定响应中应展开的字段。

创建支付意图

创建支付意图后，请关联支付方式并确认以继续支付。

在创建时使用 confirm=true 相当于在同一请求中同时创建并确认支付意图。应用 confirm=true 可启用 confirm API 中的所有参数。

端点：https://api.stripe.com/v1/payment_intents

操作：POST

备注

confirm 请求必须通过 HTTPS 进行。

示例

cURL 示例：

curl -X POST https://api.stripe.com/v1/payment_intents \
  -u <YOUR_SECRET_KEY>: \
  -d "amount=212&currency=usd&payment_method=pm_card_visa&confirm=true"

响应

响应将返回标准状态码。

200: OK

{
    "id": "pi_3Rsx4dDtWMrPDtgt0mUrePJ9",
    "object": "payment_intent",
    "amount": 212,
    "amount_capturable": 0,
    "amount_details": {
        "tip": {}
    },
    "amount_received": 0,
    "application": null,
    "application_fee_amount": null,
    "automatic_payment_methods": {
        "allow_redirects": "always",
        "enabled": true
    },
    "canceled_at": null,
    "cancellation_reason": null,
    "capture_method": "automatic_async",
    "client_secret": "pi_3Rsx4dDtWMrPDtgt0mUrePJ9_secret_7sqfufxuIYiBhbw52Vi51Z47o",
    "confirmation_method": "automatic",
    "created": 1754447247,
    "currency": "usd",
    "customer": null,
    "description": null,
    "last_payment_error": null,
    "latest_charge": null,
    "livemode": false,
    "metadata": {},
    "next_action": null,
    "on_behalf_of": null,
    "payment_method": null,
    "payment_method_configuration_details": {
        "id": "pmc_1RsGk1DtWMrPDtgtcaQ0d3Sg",
        "parent": null
    },
    "payment_method_options": {
        "amazon_pay": {
            "express_checkout_element_session_id": null
        },
        "card": {
            "installments": null,
            "mandate_options": null,
            "network": null,
            "request_three_d_secure": "automatic"
        },
        "cashapp": {},
        "klarna": {
            "preferred_locale": null
        },
        "link": {
            "persistent_token": null
        }
    },
    "payment_method_types": [
        "card",
        "klarna",
        "link",
        "cashapp",
        "amazon_pay"
    ],
    "processing": null,
    "receipt_email": null,
    "review": null,
    "setup_future_usage": null,
    "shipping": null,
    "source": null,
    "statement_descriptor": null,
    "statement_descriptor_suffix": null,
    "status": "requires_payment_method",
    "transfer_data": null,
    "transfer_group": null
}

400: Bad Request

{
  "error": {
    "code": "parameter_invalid_integer",
    "doc_url": "https://stripe.com/docs/error-codes/parameter-invalid-integer",
    "message": "Invalid integer: <integer>",
    "param": "amount",
    "request_log_url": "https://dashboard.stripe.com/test/logs/req_UQf6XBwBl9yk66?t=1734829676",
    "type": "invalid_request_error"
  }
}

401: Unauthorized

{
  "error": {
    "type": "invalid_request_error",
    "message": "Invalid API Key provided: sk_test_********************1234"
  }
}

参数

请求体参数

参数	类型	描述
amount	整数	(必填) 拟收取的金额。一个正整数，表示以最小货币单位计的收费金额（例如，100 美分即 1.00 美元）。
currency	字符串	(必填) 三字母 ISO 货币代码，小写。必须是受支持的货币。
confirm	布尔值	设置为 true 以尝试立即确认此 PaymentIntent。
customer	字符串	此 PaymentIntent 所属的客户 ID（如有）。
description	字符串	附加到该对象上的任意字符串。
payment_method	字符串	要附加到此 PaymentIntent 上的支付方式 ID。
payment_method_types[]	字符串数组	此 PaymentIntent 可使用的支付方式类型列表。
shipping	对象	PaymentIntent 的配送信息。
statement_descriptor	字符串	显示在客户信用卡账单上的任意字符串。
statement_descriptor_suffix	字符串	提供显示在客户信用卡账单上的附加详细信息。
expand[]	字符串数组	指定响应中应展开的字段。

搜索支付意图

使用 Stripe 的搜索查询语言，您可以搜索之前创建的 Payment Intents。

请勿在需要严格一致性的“写后读”流程中使用搜索请求。在正常运行情况下，数据可在不到一分钟内被搜索到。在系统故障期间，新数据或更新数据的传播有时可能会延迟长达一小时。

备注

该搜索功能不适用于印度的商户。

端点：https://api.stripe.com/v1/payment_intents/search

操作：GET

示例

cURL 示例：

curl -X GET "https://api.stripe.com/v1/payment_intents/search?query=amount:1000" \
  -u <YOUR_SECRET_KEY>:

响应

响应将返回标准状态码。

200: OK

{
  "object": "search_result",
  "data": [],
  "has_more": false,
  "next_page": null,
  "url": "/v1/payment_intents/search"
}

400: Bad Request

{
  "error": {
    "code": "parameter_invalid_string",
    "doc_url": "https://stripe.com/docs/error-codes/parameter-invalid-string",
    "message": "Provide a query parameter with a valid search query string.",
    "param": "query",
    "type": "invalid_request_error"
  }
}

401: Unauthorized

{
  "error": {
    "type": "invalid_request_error",
    "message": "Invalid API Key provided: sk_test_********************1234"
  }
}

参数

查询参数

参数	类型	描述
expand[]	字符串数组	指定响应中应展开的字段。
limit	整数	返回对象数量的限制。限制范围为 1 到 100，默认值为 10。
page	字符串	用于分页浏览多页结果的页码。首次调用时请勿包含此参数。请使用前一次响应中返回的 next_page 值来请求后续结果。
query	字符串	(必填) 搜索查询字符串。请参阅搜索查询语言以及支付意图支持的查询字段列表。