Refunds

Initiate refunds for settled payments and track their status.

A refund returns funds for a payment, in full or in part. Before creating a refund, check eligibility to learn the remaining refundable amount and whether you must collect the payer's bank details.

Amount Format

All amounts are in minor currency units (e.g., cents for EUR) as integers (e.g., 2500 for €25.00).

Check Refund Eligibility

GET /payment-executor/integration/v1/payments/{paymentId}/refund-eligibility

Returns refund eligibility and limits for a payment. Call this before showing a refund form.

Request

curl https://api.paysera.com/payment-executor/integration/v1/payments/{paymentId}/refund-eligibility \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response

{
  "eligible": true,
  "reason": null,
  "refunded_amount": 0,
  "pending_refunds": 0,
  "remaining_refundable": 2500,
  "currency": "EUR",
  "min_refund_amount": 1,
  "max_refund_amount": 2500,
  "estimated_fee_amount": 0,
  "estimated_fee_currency": "EUR",
  "fee_type": "flat",
  "requires_manual_payer_data": false
}

Response Fields

Field	Type	Description
eligible	boolean	Whether the payment can be refunded
reason	string	Ineligibility reason code (nullable, e.g. PAYMENT_NOT_SETTLED)
refunded_amount	integer	Amount already refunded
pending_refunds	integer	Amount in in-progress refunds
remaining_refundable	integer	Amount still available to refund
currency	string	ISO 4217 currency
min_refund_amount	integer	Minimum allowed refund amount
max_refund_amount	integer	Maximum allowed refund amount
estimated_fee_amount	integer	Estimated refund fee
estimated_fee_currency	string	Fee currency
fee_type	string	Fee type
requires_manual_payer_data	boolean	When true, you must collect the payer's IBAN and name

requires_manual_payer_data

When this is true, your UI must collect the payer's IBAN and name and send them as payer_iban / payer_name when creating the refund.

Create a Refund

POST /payment-executor/integration/v1/payments/{paymentId}/refunds

Initiates a refund for a payment.

Idempotency required

This endpoint requires an Idempotency-Key header. Replaying the same key with the same payload returns the original response (200); replaying it with a different payload returns 409. Initial creation returns 201.

Request

curl -X POST https://api.paysera.com/payment-executor/integration/v1/payments/{paymentId}/refunds \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f3c1e90-1b2a-4d5e-9f8a-0c1d2e3f4a5b" \
  -d '{
    "amount": 2500,
    "currency": "EUR",
    "reference": "REFUND-001"
  }'

Headers

Header	Required	Description
Idempotency-Key	Yes	Unique key that makes the request safe to retry

Request Parameters

Parameter	Type	Required	Description
amount	integer	Yes	Amount in minor units (≥ 1)
currency	string	Yes	ISO 4217 currency
reference	string	No	Merchant reference (max 255 chars)
payer_iban	string	No	Payer IBAN (max 34 chars)
payer_name	string	No	Payer name (max 140 chars)

note

payer_iban and payer_name must be provided together. The endpoint returns 422 if the payment is not eligible for refund.

Response

{
  "refund_id": "1a3b5c7d-2e4f-4a6b-8c0d-3e5f7a9b1c2d",
  "payment_id": "0c2d4e6a-1b3c-4d5e-9f8a-2b4c6d8e0f12",
  "amount": 2500,
  "currency": "EUR",
  "status": "initiated",
  "idempotency_key": "7f3c1e90-1b2a-4d5e-9f8a-0c1d2e3f4a5b",
  "workflow_id": "refund-1a3b5c7d",
  "created_at": 1736440000
}

Status values: initiated, processing, completed, failed.

Get a Refund

GET /payment-executor/integration/v1/payments/{paymentId}/refunds/{refundId}

Retrieves a single refund by its identifier.

Response

{
  "id": "1a3b5c7d-2e4f-4a6b-8c0d-3e5f7a9b1c2d",
  "payment_id": "0c2d4e6a-1b3c-4d5e-9f8a-2b4c6d8e0f12",
  "amount": 2500,
  "currency": "EUR",
  "status": "completed",
  "type": "full",
  "method": "swedbank",
  "reason": "Customer request",
  "external_reference": "EXT-REF-55",
  "fee_amount": 0,
  "fee_currency": "EUR",
  "created_at": 1736440000,
  "updated_at": 1736440600
}

List Refunds

GET /payment-executor/integration/v1/payments/{paymentId}/refunds

Returns a cursor-paginated list of refunds for a payment, ordered by created_at descending.

Query Parameters

Parameter	Type	Description
cursor	string	Pagination cursor
limit	integer	Page size
sort	string	Sort order

Related Documentation

• Payments - Read payment records
• Activity - Refund events also appear in the payment activity feed