Create a refund

curl --request POST \
  --url https://api.flowlix.dev/v1/refunds \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "payment_id": "pay_q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E",
  "amount": 1500,
  "reason": "requested_by_customer",
  "metadata": {
    "order_id": "ord_1234"
  }
}
'

{
  "id": "ref_L9xQ4wE2rT8yU6iO3pA7sD1f",
  "payment_id": "pay_q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E",
  "amount": 1500,
  "currency": "EUR",
  "reason": "requested_by_customer",
  "status": "PENDING",
  "created_at": 123,
  "updated_at": 123,
  "livemode": false,
  "metadata": {},
  "decline_code": "<string>",
  "decline_message": "<string>",
  "completed_at": 123
}

Refunds

Create a refund

Refunds a payment that has already succeeded. The amount is always required. To refund the full payment, set amount to the payment’s remaining refundable amount. The refund uses the same currency as the original payment; currency is not accepted on the refund request.

A payment can be refunded multiple times as long as the accumulated refunded amount does not exceed the original.

The refund is accepted for processing and starts with status: "PENDING". Monitor the refund’s progress via the returned Refund object, subsequent GET /v1/payments/{id} calls, or webhooks. The status transitions to SUCCEEDED on provider confirmation or FAILED on decline.

Every refund is recorded with a mandatory reason and is linked to the original payment via payment_id.

Idempotency

Use the Idempotency-Key header to safely retry refund requests. The idempotency contract is body-hash-based: a retry with the exact same body returns the original response, while a retry with the same key but any different field, including a different reason or amount, is rejected with 409 idempotency_error. Pick a deterministic key tied to the refund operation and resend the same body on retries.

POST

refunds

Create a refund

curl --request POST \
  --url https://api.flowlix.dev/v1/refunds \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "payment_id": "pay_q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E",
  "amount": 1500,
  "reason": "requested_by_customer",
  "metadata": {
    "order_id": "ord_1234"
  }
}
'

{
  "id": "ref_L9xQ4wE2rT8yU6iO3pA7sD1f",
  "payment_id": "pay_q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E",
  "amount": 1500,
  "currency": "EUR",
  "reason": "requested_by_customer",
  "status": "PENDING",
  "created_at": 123,
  "updated_at": 123,
  "livemode": false,
  "metadata": {},
  "decline_code": "<string>",
  "decline_message": "<string>",
  "completed_at": 123
}

Authorizations

Authorization

string

header

required

Use your secret API key as the Bearer token. Test mode keys start with api_test_sk_ and live mode keys start with api_live_sk_. Both modes use the same API host; the mode is determined by the key.

Authorization: Bearer api_test_sk_abc123def456

Headers

Idempotency-Key

string

required

A unique key to ensure the request is processed only once. If a request with the same idempotency key and the same body has already been processed successfully, the original response is returned. Non-2xx responses are not cached, so callers may retry after errors. Keys expire after 24 hours.

For one-shot requests, such as creating a payment from a checkout button, a random UUIDv4 is fine. For requests tied to a specific business operation, such as refunding an order, a deterministic key is preferred so retries collapse correctly across processes.

Maximum string length: 255

Body

application/json

payment_id

string

required

Unique opaque identifier for a payment (pay_ prefix + random alphanumeric suffix).

Pattern: ^pay_[A-Za-z0-9]{24}$

Example:

"pay_q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E"

amount

integer<int64>

required

Refund amount in minor units, in the same currency as the original payment. Use the remaining refundable amount for a full refund.

Required range: x >= 1

Example:

1500

reason

enum<string>

required

Reason for the refund. fraudulent should be used only when the merchant believes the payment was fraudulent.

Available options:

duplicate,

fraudulent,

requested_by_customer

Example:

"requested_by_customer"

metadata

object

Merchant-provided key-value metadata. Values may be any valid JSON value.

Show child attributes

Response

Refund accepted and a Refund object was created. The refund may still be PENDING or PROCESSING; use the returned status, subsequent payment retrievals, or webhooks to track completion.

A refund against a payment.

string

required

Unique opaque identifier for a refund (ref_ prefix + random alphanumeric suffix).

Pattern: ^ref_[A-Za-z0-9]{24}$

Example:

"ref_L9xQ4wE2rT8yU6iO3pA7sD1f"

payment_id

string

required

Unique opaque identifier for a payment (pay_ prefix + random alphanumeric suffix).

Pattern: ^pay_[A-Za-z0-9]{24}$

Example:

"pay_q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E"

amount

integer<int64>

required

Refund amount in minor units.

Required range: x >= 1

Example:

1500

currency

enum<string>

required

Three-letter ISO 4217 currency code. Currently supported for card acquiring: EUR.

Available options:

EUR

Example:

"EUR"

reason

enum<string>

required

Reason for the refund. fraudulent should be used only when the merchant believes the payment was fraudulent.

Available options:

duplicate,

fraudulent,

requested_by_customer

Example:

"requested_by_customer"

status

enum<string>

required

Current refund lifecycle status. Refunds normally move from PENDING to PROCESSING, then to SUCCEEDED, FAILED, or CANCELED. Some payment methods may require customer or merchant action before a refund can complete.

Available options:

PENDING,

PROCESSING,

REQUIRES_ACTION,

SUCCEEDED,

FAILED,

CANCELED

Example:

"PENDING"

created_at

integer<int64>

required

Unix timestamp when the refund was created.

updated_at

integer<int64>

required

Unix timestamp when the refund was last updated.

livemode

boolean

required

Whether this refund was created using a live API key.

Example:

false

metadata

object

Merchant-provided metadata. Values may be any valid JSON value.

Show child attributes

decline_code

string | null

Machine-readable code when the refund fails.

decline_message

string | null

Human-readable explanation when the refund fails.

completed_at

integer<int64> | null

Unix timestamp when the refund reached a terminal status.

Retrieve a payment