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

Start a train refund

Start a refund operation for selected refundable order items.

Share

Start a refund operation for selected refundable order items.

Authentication and headers

HeaderDescription
AuthorizationBearer <secret_key>. Keep the secret on the server and never write it to client logs.
X-Travelandz-Id<public_key>:<profile_code>, where the persisted profile code has the form dp_<12 alphanumeric>.
Content-Typeapplication/json for requests with a JSON body.

Request

The body requires a non-empty itemIds array of non-empty strings.

Request Params Schema

gdsprovider
enum
0
Yes
Currently 0
orderId
stringYes
Order id returned by order creation.

Request Body Schema

itemIds
arrayYes
itemIds[]
string[]Yes

Success response

Returns result with operation id, state, timestamp, total refund amount and item states. State can be success, pending or error.

Response Body Schema

result
objectYes
resultid
stringYes
resultstate
enum
successpendingerror
Yes
resultcreatedAt
string
Format: ISO 8601
Yes
resulttotalRefundAmount
objectYes
resulttotalRefundAmountamount
numberYes
resulttotalRefundAmountcurrency
stringYes
resultitems
arrayYes
resultitems[]id
stringYes
resultitems[]state
enum
successpendingerror
Yes
resultitems[]amount
objectYes
resultitems[]amountamount
numberYes
resultitems[]amountcurrency
stringYes

Errors

  • 400 for validation or unknown fields.
  • 401 or 403 for invalid API credentials.
  • 500 internal_communication_error or unknown_error for provider failures.
  • order_already_refunded when the order was already refunded.
  • order_refund_items_not_found when requested items are unavailable.

Usage notes

A successful HTTP response can still have a pending operation state. Poll the refund status endpoint for completion.

cURL example

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"]}'