POST/v1/trains/order/:gdsprovider/:orderId/refund

发起火车退款

为选定的可退款订单项目发起退款操作。

分享

为选定的可退款订单项目发起退款操作。

认证和请求头

请求头说明
AuthorizationBearer <secret_key>。密钥只能保存在服务器端，不能写入客户端日志。
X-Travelandz-Id<public_key>:<profile_code>，持久化的 profile code 格式为 dp_<12 位字母数字>。
Content-Type带 JSON body 的请求使用 application/json。

请求

body 需要非空字符串数组 itemIds，且每个字符串不能为空。

请求参数结构

gdsprovider
enum
0
是
Currently 0
orderId
string是
Order id returned by order creation.

请求体结构

itemIds
array是
itemIds[]
string[]是

成功响应

返回 result，包含操作 id、状态、时间戳、退款总额和项目状态。状态可以是 success、pending 或 error。

响应体结构

result
object是
resultid
string是
resultstate
enum
successpendingerror
是
resultcreatedAt
string
格式: ISO 8601
是
resulttotalRefundAmount
object是
resulttotalRefundAmountamount
number是
resulttotalRefundAmountcurrency
string是
resultitems
array是
resultitems[]id
string是
resultitems[]state
enum
successpendingerror
是
resultitems[]amount
object是
resultitems[]amountamount
number是
resultitems[]amountcurrency
string是

错误

  • 400 表示验证失败或存在未知字段。
  • 401 或 403 表示 API 凭证无效。
  • 供应方失败时返回 500 internal_communication_error 或 unknown_error。
  • 订单已退款时返回 order_already_refunded。
  • 请求的项目不可用时返回 order_refund_items_not_found。

使用说明

HTTP 成功响应的操作状态仍可能为 pending。请通过退款状态端点查询完成情况。

cURL 示例

bash
bash
curl --request POST \
  --url "https://api.sandbox.travelandz.com/v1/trains/order/0/order_123/refund" \
  --header "Authorization: Bearer $TRAVELANDZ_SECRET_KEY" \
  --header "X-Travelandz-Id: $TRAVELANDZ_PUBLIC_KEY:$TRAVELANDZ_PROFILE_CODE" \
  --header "Content-Type: application/json" \
  --data '{"itemIds":["refund_item_123"]}'