退款 API 函数

创建退款

为已创建但尚未退款的扣款创建退款。 您可以指定退款金额，或者不指定金额以退还全部交易金额。退款将使用与交易相同的货币，并通过与交易相同的支付方式进行。

同一笔交易不能被多次退款。 如果您尝试对已退款的交易再次退款，系统将返回错误。 若尝试退款金额超过原始收费金额，也会出现此情况。

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

操作：POST

示例

cURL 示例：

curl -X POST https://api.stripe.com/v1/refunds \
  -u <YOUR_SECRET_KEY>: \
  -d "charge=ch_1NirD82eZvKYlo2CIvbtLWuY"

响应

响应将返回标准状态码。

200: OK

{
  "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

{
  "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	整数	退款金额（单位为美分）。若未指定，将退还全部收费金额。
charge	字符串	（必填） 待退款的收费 ID。
currency	字符串	三字母 ISO 货币代码，小写。必须是受支持的货币。如果未指定，将使用扣款时的货币。
expand[]	字符串数组	指定响应中应展开的字段。
customer	字符串	扣款所属客户的 ID。
reason	字符串	退款原因。若设置此字段，可能的取值为 duplicate、fraudulent 或 requested_by_customer。若设置为 fraudulent，与该交易关联的卡片和邮箱将被添加到您的屏蔽列表中，并有助于改善 Stripe 的欺诈检测。
payment_intent	字符串	待退款的 PaymentIntent ID。
refund_application_fee	布尔型	指示是否应退还申请费。若全额退款，申请费也将一并退还。否则，申请费将按退款比例退还。申请费仅适用于生成该扣款的申请。
origin	字符串	退款的来源。
reverse_transfer	布尔值	指示是否应逆转转账。转账将按退款金额（全额或部分退款）的比例进行逆转。
instructions_email	字符串	当使用不支持退款的支付方式时，使用客户的电子邮件地址发送退款说明。

更新退款

通过设置传入参数的值来更新指定的退款。 未提供的参数将保持不变。这有助于存储有关退款的附加信息。

端点：https://api.stripe.com/v1/refunds/{id}

操作：POST

示例

cURL 示例：

curl -X POST `https://api.stripe.com/v1/refunds/{id}` \
  -u <YOUR_SECRET_KEY>: \
  -d "metadata[order_id]=6735"

响应

响应将返回标准状态码。

200: OK

{
  "id": "re_1Nispe2eZvKYlo2Cd31jOCgZ",
  "object": "refund",
  "amount": 1000,
  "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": {
    "order_id": "6735"
  },
  "payment_intent": "pi_1GszsK2eZvKYlo2CfhZyoZLp",
  "reason": null,
  "receipt_number": null,
  "source_transfer_reversal": null,
  "status": "succeeded",
  "transfer_reversal": 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"
  }
}

参数

请求体参数

参数	类型	描述
metadata	对象	可附加到对象上的键值对集合。这有助于以结构化格式存储有关该对象的附加信息。
expand[]	字符串数组	指定响应中应展开的字段。

路径变量

名称	类型	必填	描述
id	字符串	必填	要更新的退款 ID。

检索退款

检索特定退款的详细信息。

端点：https://api.stripe.com/v1/refunds/{id}

操作：GET

示例

cURL 示例：

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

响应

响应将返回标准状态码。

200: OK

{
  "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

{
  "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"
  }
}

参数

查询参数

参数	类型	描述
expand[]	字符串数组	指定响应中应展开的字段。

路径变量

名称	类型	必填	描述
id	字符串	必填	要检索的退款 ID。

列出所有退款

返回现有退款的列表。退款按排序顺序返回，最近的退款排在最前面。默认返回最近的 10 笔退款。

接口地址：https://api.stripe.com/v1/refunds

操作：GET

示例

cURL 示例：

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

响应

响应将返回标准状态码。

200: OK

{
  "object": "list",
  "url": "/v1/refunds",
  "has_more": false,
  "data": [
    {
      "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

{
    "error": {
        "code": "resource_missing",
        "doc_url": "https://stripe.com/docs/error-codes/resource-missing",
        "message": "No such charge: 'ch_1NirD82eZvKYlo2CIvbtLWuY'",
        "param": "charge",
        "request_log_url": "https://dashboard.stripe.com/test/logs/req_HIH2jWkJGecwCk?t=1754504399",
        "type": "invalid_request_error"
    }
}

401: Unauthorized

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

参数

参数	类型	说明
charge	字符串	需查询退款的费用 ID。若未指定，将返回所有退款。
created	字典	仅返回在指定日期区间内创建的退款。该字典可包含以下键：gt、gte、lt、lte。
ending_before	字符串	分页用的光标。使用对象 ID ending_before 来定义您在列表中的位置。如果您发起列表请求并收到 100 条结果，从 obj_bar 开始，后续调用可包含 ending_before=obj_bar 来获取列表的前一页。
limit	整数	返回对象数量的限制。限制范围为 1 到 100。默认值为 10。
payment_intent	字符串	用于检索退款的 PaymentIntent ID。如果未指定，将返回所有退款。
starting_after	字符串	分页中使用的游标。 使用对象 ID starting_after 来定义您在列表中的位置。如果您发起列表请求并收到 100 条结果，最后一条为 obj_foo，则后续调用可包含 starting_after=obj_foo 来获取列表的下一页。
expand[]	字符串数组	指定响应中应展开的字段。