Skip to main content

Refund API

POST/rest/refund

Refund API is used to refund full or partial amounts of payments that were made by merchants' customers. There can be multiple refunds per transaction, however, the combined sum of refunds should not exceed the total amount of the transaction.

note

Partial refunds are not supported by all payment methods. Please check the Transaction Types section from Payment Methods if your payment method supports it.

Refund API Request​

transaction_idStringrequired
ID of the transaction to be refunded
merchant_referenceString
Default value if not provided: merchant_reference from original transaction. String length different per payment method
amountFloat
When not given, full amount will be refunded. Can be smaller but not larger than the original amount
execution_dateDate
Optional date of the event. Format: YYYY-MM-DD
commentString
Any reference you may want to add to this refund. For internal purposes, not shown to customer. Please check Payment Methods for specific values.
Example Request
POST /rest/refund
Authorization: Basic <base64(api_key:api_password)>
Content-Type: application/json
{
"transaction_id": "f3ba29ea-5644-4e4b-aacd-8d854ebb3d46",
"merchant_reference": "12345678 - Test Shop",
"amount": "10.00",
"execution_date": "2025-02-19",
"comment": "Customer returned item"
}

Refund API Response​

note

The response is attributed to the Refund object — not the transaction. Thus, the status_code and status will differ from transaction values.

transaction_idString
ID of the refunded transaction
refund_idString
ID of the created refund object
statusString
Status of the refund (STARTED, SUCCESS, ERROR)
status_codeInteger
Status code of the refund (0 for STARTED, 1 for SUCCESS, 2 for ERROR)
error_codeInteger
Error code for the response
Example Response
{
"transaction_id": "f3ba29ea-5644-4e4b-aacd-8d854ebb3d46",
"refund_id": "2ce3297b-1bda-4637-9375-ecf224cdefc7",
"status_code": 1,
"status": "successful",
"error_code": 0
}

Postbacks​

When a refund is completed or its status changes, the API sends an HTTP POST request to the postback_url associated with the original transaction. This allows your system to receive real-time refund updates.

info

All postback URLs must use HTTPS and support TLS 1.2 or higher. Non-secure or HTTP URLs will be rejected.

Refund Postback — Completed​

transaction_idString
ID of the original transaction
payment_typeString
Payment type code
status_codeInteger
Numeric status code
statusString
Text representation of the transaction status (e.g. refunded)
order_idString
Your internal order or invoice reference
messageString
Additional information about the refund result
refund_remittance_infoString
Remittance information associated with the refund. Sent when a Refund becomes completed. Specific to Wero.
refund_wallet_activity_referenceString
Wallet activity reference for the refund. Specific to Wero. Only included when available.
payer_locationString
Payer location. Specific to Wero. Only included when available.
additional_transaction_dataString
Additional payment information provided by you
amountFloat
Amount of the refund
refund_status_codeInteger
Status of the refund: 0 Started, 1 Success, 2 Error, 3 Local, 4 Reversed, 5 Declined
refund_idString
ID of the created refund object
included_feesString
Fees included in the amount
checksumString
Checksum of parameters. Use your webhook key to verify message integrity.
Example Refund Completed
{
"transaction_id": "609c412f-53bf-4185-bdb4-7c34225607a6",
"payment_type": "wero",
"status_code": 7,
"status": "refunded",
"order_id": "123000",
"message": "REFUND SETTLED",
"refund_remittance_info": "12345678 - Test Shop",
"refund_wallet_activity_reference": "RWARb23dc80e71af",
"payer_location": "DE",
"additional_transaction_data": null,
"amount": 10.0,
"refund_status_code": 1,
"refund_id": "58dd2ec9-c6b4-40ec-92d2-047d2913b209",
"included_fees": "0.00",
"checksum": "a7227a1ee524d9da88515cb162656db21701cc74"
}

Refund Postback — Declined​

transaction_idString
ID of the original transaction
payment_typeString
Payment type code
status_codeInteger
Numeric status code
statusString
Text representation of the transaction status
order_idString
Your internal order or invoice reference
messageString
Additional information about the refund result
refund_reason_codeString
Rejection reason code for refund transfers in ISO format (e.g. AC04). See EPC guidance
refund_wallet_activity_referenceString
Wallet activity reference for the refund. Specific to Wero. Only included when available.
payer_locationString
Payer location. Specific to Wero. Only included when available.
additional_transaction_dataString
Additional payment information provided by you
amountFloat
Amount of the refund
refund_status_codeInteger
Status of the refund: 0 Started, 1 Success, 2 Error, 3 Local, 4 Reversed, 5 Declined
refund_idString
ID of the created refund object
included_feesString
Fees included in the amount
checksumString
Checksum of parameters. Use your webhook key to verify message integrity.
Example Refund Declined
{
"transaction_id": "609c412f-53bf-4185-bdb4-7c34225607a6",
"payment_type": "wero",
"status_code": 7,
"status": "refunded",
"order_id": "123000",
"message": "REFUND REJECTED",
"refund_reason_code": "AC04",
"refund_wallet_activity_reference": "RWARb23dc80e71af",
"payer_location": "DE",
"additional_transaction_data": null,
"amount": 10.0,
"refund_status_code": 5,
"refund_id": "58dd2ec9-c6b4-40ec-92d2-047d2913b209",
"included_fees": "0.00",
"checksum": "a7227a1ee524d9da88515cb162656db21701cc74"
}

For details on retry policy and signature verification, see Postbacks.

Last updated on