Refund a payment

Performs a full refund on a payment that has already succeeded. The payment status transitions to refunded and the full amount is returned to the customer’s card.

A payment can only be refunded once. Attempting to refund a payment that is already refunded, still pending, or has failed will return an error.

Use the Idempotency-Key header to safely retry refund requests.

POST /v1/payments/{id}/refund

Refund a payment

cURL

curl --request POST \
  --url https://api.flowlix.eu/v1/payments/{id}/refund \
  --header 'Authorization: Bearer <token>'

200

refunded

{
  "id": "pay_1N3fKx2eZvKYlo2C0XjMr8pV",
  "object": "payment",
  "amount": 4999,
  "currency": "eur",
  "status": "refunded",
  "description": "Order #1234",
  "card": {
    "brand": "visa",
    "last4": "4242",
    "exp_month": 12,
    "exp_year": 2027,
    "country": "US"
  },
  "customer": {
    "email": "[e-mail]",
    "name": "Jenny Rosen"
  },
  "metadata": {
    "order_id": "ord_1234",
    "sku": "WIDGET-XL"
  },
  "decline_code": null,
  "decline_message": null,
  "redirect_url": null,
  "refunded_at": 1719878400,
  "succeeded_at": 1719792000,
  "failed_at": null,
  "created": 1719792000,
  "livemode": false
}

Authorizations

Authorization · string · header · required

Use your secret API key as the Bearer token. Test mode keys start with fl_test_sk_ and live mode keys start with fl_live_sk_.

Authorization: Bearer fl_test_sk_abc123def456

Headers

Idempotency-Key · string

A unique key to ensure the request is processed only once. If a request with the same idempotency key has already been processed, the original response is returned. Keys expire after 24 hours. We recommend UUIDv4 values.

Maximum string length: 255

Flowlix-Version · string

The API version to use for this request. Defaults to your account's default version if not specified. Format: YYYY-MM-DD.

Pattern: ^\d{4}-\d{2}-\d{2}$

Path Parameters

id · string · required

The unique identifier of the payment (starts with pay_).

Pattern: ^pay_[a-zA-Z0-9-]+$

Response

200

application/json

Payment refunded successfully.

A Payment object represents a single attempt to move money. It is created when you submit a payment request and is updated as the payment progresses through its lifecycle.

id · string

Unique identifier for the payment.

Pattern: ^pay_[a-zA-Z0-9-]+$

Example:

"pay_1N3fKx2eZvKYlo2C0XjMr8pV"

object · enum<string>

Object type; always payment.

Available options: payment

Example:

"payment"

amount · integer<int64>

The payment amount in minor units.

Example:

4999

currency · string

Three-letter ISO 4217 currency code.

Example:

"eur"

status · enum<string>

The current status of the payment.

• pending -- The payment has been created but not yet completed (HPP flow).
• succeeded -- The payment was successful.
• failed -- The payment was declined or failed.
• refunded -- The payment was refunded.

Available options: pending, succeeded, failed, refunded

Example:

"succeeded"

description · string | null

The description attached to the payment.

Example:

"Order #1234"

card · object

The masked card details. null for HPP payments that have not yet been completed.

Show child attributes

customer · object

The customer associated with the payment.

Show child attributes

metadata · object

Arbitrary key-value metadata attached to the payment.

Show child attributes

Example:

{ "order_id": "ord_1234" }

decline_code · string | null

If the payment was declined, the decline code indicating the reason. See the decline codes reference for details.

Example:

null

decline_message · string | null

If the payment was declined, a human-readable message explaining why.

Example:

null

redirect_url · string<uri> | null

For HPP payments, the URL of the hosted payment page to redirect the customer to. null for direct API payments.

Example:

null

refunded_at · integer<int64> | null

Unix timestamp when the payment was refunded, or null if not refunded.

Example:

null

succeeded_at · integer<int64> | null

Unix timestamp when the payment succeeded, or null if not yet succeeded.

Example:

1719792000

failed_at · integer<int64> | null

Unix timestamp when the payment failed, or null if not failed.

Example:

null

created · integer<int64>

Unix timestamp when the payment was created.

Example:

1719792000

livemode · boolean

Whether this payment was created using a live API key (true) or a test API key (false).

Example:

false