Create Refund

Required scope: payment:refund

Issues a refund against a payment. amountMinor is an integer minor currency amount and must be greater than zero. This moves money, so it is not idempotent except through requestId: requestId is a UUID idempotency key and reusing it returns the original refund rather than issuing a second one.

Some providers settle refunds manually. When they do, the response includes a manualRefundTask describing the payout to complete outside HeyX.

Generated Reference

POST /public-api/publicapi.v1.Payment/CreateRefund

Creates a refund against a payment. Moves money; idempotent per request_id. Only Mollie and manual providers are supported; others are rejected.

Request CreateRefundRequest

Response CreateRefundResponse

CreateRefundRequest

Field	Type	Description
payment_id	string	Payment to refund.
amount_minor	int64	Amount to refund in minor currency units.
reason	optional string	Optional human-readable refund reason.
request_id	string	Idempotency key; reusing it returns the original refund.

CreateRefundResponse

Field	Type	Description
refund	Refund	The created or existing refund.
manual_refund_task	optional ManualRefundTask	Present when the refund requires a manual human payout action.

Related Types

Refund

Field	Type	Description
id	string	Stable refund identifier.
payment_id	optional string	Payment the refund was issued against, when linked.
customer_id	string	Customer the refund belongs to.
status	RefundStatus	Refund lifecycle status.
amount_minor	int64	Requested refund amount in minor currency units.
amount_refunded_minor	int64	Amount actually refunded in minor currency units.
currency	string	ISO 4217 currency code.
reason	optional string	Refund reason, when provided.
refunded_at	optional int64	Time the refund completed as unix seconds, when completed.
created_at	int64	Creation time as unix seconds.
updated_at	int64	Last update time as unix seconds.

ManualRefundTask

Field	Type	Description
id	string	Stable task identifier.
status	string	Task lifecycle status.
amount_minor	int64	Amount to be paid out in minor currency units.
currency	string	ISO 4217 currency code.
reference_number	string	Reference number for the payout.

Request

{
  "paymentId": "<payment-id>",
  "amountMinor": "12500",
  "reason": "Partial return",
  "requestId": "<uuid>"
}

Response

{
  "refund": {
    "id": "<refund-id>",
    "paymentId": "<payment-id>",
    "customerId": "<customer-id>",
    "status": "PUBLIC_REFUND_STATUS_PENDING",
    "amountMinor": "12500",
    "amountRefundedMinor": "0",
    "currency": "EUR",
    "createdAt": "1737936000",
    "updatedAt": "1737936000"
  }
}