创建退款
为已结算的扣款或 PaymentIntent 发起退款。传入自定义金额,或省略该参数以退还剩余余额。Stripe 以原始货币将资金退回原支付方式。
退款金额不能超过剩余余额。 对已全额退款的扣款,Stripe 拒绝任何退款。金额超过剩余余额时,Stripe 同样拒绝。
POST https://api.stripe.com/v1/refunds
示例
运行以下 cURL 命令发送请求。
cURL
curl -X POST https://api.stripe.com/v1/refunds \
-u "<YOUR_SECRET_KEY>:" \
-d "charge=ch_1NirD82eZvKYlo2CIvbtLWuY"
参数
正文参数
| 参数 | 类型 | 必需 | 说明 |
|---|---|---|---|
amount | 整数 | 可选 | 退款金额,以最小货币单位表示,例如 USD 用美分。仅退还扣款中剩余未退的金额。省略时,Stripe 退还全部剩余余额。 |
charge | 字符串 | 条件必填 | 要退款的扣款。传入 charge 或 payment_intent。 |
currency | 字符串 | 可选 | 小写的三字母 ISO 货币代码。必须使用受支持的货币。 |
customer | 字符串 | 可选 | 用其客户余额为本次退款提供资金的客户。 |
metadata | 对象 | 可选 | 要附加到退款的一组键值对。用它以结构化格式存储额外信息。 |
reason | 字符串 | 可选 | 退款原因。设置后可选值为 duplicate、fraudulent 或 requested_by_customer。设为 fraudulent 时,Stripe 将关联的卡和邮箱加入您的阻止列表,从而提升欺诈检测能力。 |
payment_intent | 字符串 | 条件必填 | 要退款的 PaymentIntent。传入 charge 或 payment_intent。 |
refund_application_fee | 布尔值 | 可选 | 决定 Stripe 是否随本次扣款退还应用费用。全额退款时 Stripe 退还全部费用,部分退款时按比例退还。Stripe 仅将费用退还至创建该扣款的应用。 |
origin | 字符串 | 可选 | 退款来源。将其设为 customer_balance。 |
reverse_transfer | 布尔值 | 可选 | 决定 Stripe 是否从关联账户收回已转出的资金。Stripe 按退款金额比例冲销关联转账。全额和部分退款均适用。 |
instructions_email | 字符串 | 可选 | 当客户的支付方式不支持原生退款时,向此邮箱地址发送手动提现说明。 |
transfer_data | 对象 | 可选 | 包含目标扣款中自动转账目标账户的字典。 |
expand[] | 字符串数组 | 可选 | 标识需要补充数据并内联返回的嵌套响应对象。 |
响应
响应使用标准状态码:200 表示成功,401 表示 API 密钥无效。完整列表见 Stripe 的错误代码。
200: OK
Response
{
"id": "re_1Nispe2eZvKYlo2Cd31jOCgZ",
"object": "refund",
"amount": 212,
"balance_transaction": "txn_1Nispe2eZvKYlo2CYezqFhEx",
"charge": "ch_1NirD82eZvKYlo2CIvbtLWuY",
"created": 1692942318,
"currency": "usd",
"destination_details": {
"card": {
"reference": "123456789012",
"reference_status": "available",
"reference_type": "acquirer_reference_number",
"type": "refund"
},
"type": "card"
},
"metadata": {},
"payment_intent": "pi_1GszsK2eZvKYlo2CfhZyoZLp",
"reason": null,
"receipt_number": null,
"source_transfer_reversal": null,
"status": "succeeded",
"transfer_reversal": null
}
错误响应
400: Bad Request
Response
{
"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
Response
{
"error": {
"type": "invalid_request_error",
"message": "Invalid API Key provided: sk_test_********************1234"
}
}