Skip to main content
A miniapp asks the host app to refund a payment with refund_request. The host app returns the money to the user and reports the result with refund_status. A payment can be refunded partially and more than once, up to the amount that was charged.

refund_request

Miniapp → Host app. Asks the host app to refund an amount of a payment.

refund_status

Host app → Miniapp. Reports the state of a refund, ending with a final state.

​
Flow

​
Refund states

Final states never change. The host app must send exactly one final state for every refund it receives.

​
refund_request

Asks the host app to refund an amount of a payment it charged. Direction: Miniapp → Host app

​
Payload

​
string
required
Unique id of this refund, generated by the miniapp. It is the idempotency key: the same refund_id always means the same refund.
​
string
required
The host app payment to refund, as returned by the host app’s create order payment endpoint.
​
string
required
The miniapp order the payment belongs to, as sent in the create order payment request.
​
string
required
Amount to refund, as a string with 2 decimals.
amount can be less than the payment amount. A payment can receive several refunds, as long as their total does not exceed the amount charged.
​
string
required
ISO 4217 currency code. Always the currency of the original payment.
​
string
Optional human-readable reason, for support and reporting.
The miniapp sends it through POST /api/v1/events/miniapp/, and the host app’s Event Receiver answers with an empty body:

​
Receiver must

Deduplicate on refund_id and never refund the same refund_id twice.
Respond 200 with {} straight away, before processing the refund.
Send refund_status once the result is known, ending with a final state.

​
refund_status

Reports the state of a refund to the miniapp that requested it. Direction: Host app → Miniapp

​
Payload

​
string
required
The refund_id from refund_request.
​
string
required
The order_payment_id from refund_request.
​
string
required
One of the refund states.
​
string
required
The refunded amount, as a string with 2 decimals. Must match refund_request.
​
string
required
ISO 4217 currency code. Must match refund_request.
​
string
required
When the refund reached this state, as an ISO 8601 UTC timestamp.
​
string
Why the refund failed or was cancelled. Only for failed and cancelled.
The host app sends it through POST /api/v1/events/hostapp/, and the miniapp’s Event Receiver answers with an empty body:

​
Receiver must

Match the refund on refund_id.
Ignore updates for a refund that is already in a final state.
Respond 200 with {}.
If sending refund_request fails or times out, resend it with the same refund_id. The host app deduplicates on refund_id, so a resend can never cause a second refund.
If no final refund_status arrives within a maximum age, for example 7 days, raise an alert for manual follow-up with the host app.

​
Supported miniapps

Other miniapps are added to this table as they adopt the standard. A host app that implements these two events supports all of them.

​
Errors

Delivery errors such as a disabled Event Receiver are returned by the Event Bridge API. See Error Handling in Event Bridge.