3 endpoints
Refunds
Refund all or part of a successful payment, with a reason and your own reference — debited from the balance and linked to the original payment.
Endpoint names and descriptions come from the OpenAPI contract, in English — they cannot drift from the API.
In plain English
Give the money back, in full or in part, cleanly.
When to use it
As soon as an order is cancelled, returned or disputed. Partial refunds are possible, and several can follow each other as long as the total stays within the original payment.
How to integrate it
- 1Create the refund citing the original operation and your refund reference.
- 2The reference acts as the idempotency key: replaying the same call does not refund twice.
- 3Follow completion by webhook — a refund is not instant on the bank side.
List refunds
Returns your refunds for the key's environment, most recent first, as a paginated Page. Optionally filtered by status (PENDING, SUCCESS, FAILED).
| Field | Type | In | Required | Description |
|---|---|---|---|---|
status | enum | query | Optional | Only refunds in this status.Values PENDINGSUCCESSFAILED |
pageable | Pageable | query | Required |
Create a refund
Refunds a payment, in full or partially (refundAmount). Identify the payment by operationId or externalId. Idempotent on refundReference: replaying an already-executed reference returns the existing refund (200) without re-debiting; a fresh one returns 202 Accepted while it settles.
Schema · RefundPaymentRequest
| Field | Type | In | Required | Description |
|---|---|---|---|---|
operationId | integer (int64) | body | Optional | |
externalId | string | body | Optional | |
refundReference | string | body | Required | |
refundAmount | number | body | Optional | |
reason | string | body | Required | |
note | string | body | Optional | |
metadata | object | body | Optional |
Retrieve a refund
Fetches a refund by your refundReference or the platform refundId.
| Field | Type | In | Required | Description |
|---|---|---|---|---|
reference | string | path | Required | Your refundReference or the platform refundId. |
A question about integration?
Our technical team supports integrators from the first sandbox call through to go-live.