Create a refund for an order

POST /order/{orderNumber}/refund

Api key

Create a refund (bank transfer back to the customer) for an existing order.

plannedDate must be in the future (the date the bank transfer should be initiated).
If the customer's bank details are not yet known, the refund starts in status BANKDETAILS_MISSING and Komfortkasse asks the customer to provide their IBAN. Once received, it transitions to NEW and is executed at plannedDate.
externalReference is your own reference (e.g. RMA number) and must be unique per shop. Re-using a reference of an existing refund returns an error.

Path parameters

orderNumber string Required

Order number (unique per shop).

application/json

Body Required

externalReference string Required

Reference given by you.
amount number Required

Refund amount. Format: 0.00.
currency string Required

Refund currency.
plannedDate string Required

Planned date (date when the bank transfer should be initiated — can be delayed for technical or other reasons, e.g. waiting for bank details).

Responses

200 application/json

Refund created.
Hide response attributes Show response attributes object
- externalReference string Required
  
  Reference given by you.
- amount number Required
  
  Refund amount. Format: 0.00.
- currency string Required
  
  Refund currency.
- plannedDate string Required
  
  Planned date (date when the bank transfer should be initiated — can be delayed for technical or other reasons, e.g. waiting for bank details).
- id string
  
  Unique ID (given by Komfortkasse).
- executionDate string
  
  Date when bank transfer has been executed (null if not yet processed).
- referenceNumber string
  
  Reference given by Komfortkasse (typically starts with 'KKBT').
- status string
  
  Refund status (read only):
  
  NEW — will be transferred to bank if plannedDate is reached
  
  BANKDETAILS_MISSING — waiting for bank details from customer
  
  IN_PROCESS — being processed
  
  PROCESSED — processed by bank
  
  RETURNED — returned to original account
  
  ERROR — error
  
  CANCELLED — manually cancelled before executed
  
  LEGACY — old bank transfer, will not be processed
  
  See also Detail view refunds for a longer explanation of each status.
  
  Values are NEW, BANKDETAILS_MISSING, IN_PROCESS, PROCESSED, RETURNED, ERROR, CANCELLED, or LEGACY.
400 application/json

Invalid request — for example missing required fields or wrong format.
Hide response attribute Show response attribute object
- error string Required
  
  Error message.
401 application/json

Authentication failed — API key missing or invalid.
Hide response attribute Show response attribute object
- error string Required
  
  Error message.
404 application/json

Resource not found (e.g. unknown order number).
Hide response attribute Show response attribute object
- error string Required
  
  Error message.

POST /order/{orderNumber}/refund

curl \
 --request POST 'https://ssl.komfortkasse.eu/api/v2/order/123456/refund' \
 --header "X-Komfortkasse-API-Key: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"externalReference":"RMA-2024-001","amount":22.38,"currency":"EUR","plannedDate":"01-05-2018"}'

Request example

{
  "externalReference": "RMA-2024-001",
  "amount": 22.38,
  "currency": "EUR",
  "plannedDate": "01-05-2018"
}

Response examples (200)

{
  "externalReference": "RMA-2024-001",
  "amount": 22.38,
  "currency": "EUR",
  "plannedDate": "01-05-2018",
  "id": "12345",
  "referenceNumber": "KKBT00012345",
  "status": "NEW"
}

Response examples (400)

{
  "error": "Invalid request"
}

Response examples (401)

{
  "error": "API Key missing"
}

Response examples (404)

{
  "error": "Order not found"
}