Create a refund

curl --request POST \
  --url https://api.flowlix.eu/v1/refunds \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "payment_id": "pay_q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E",
  "amount": 1500,
  "merchant_reference": 3456789012,
  "reason": "Customer requested a refund"
}
'

import requests

url = "https://api.flowlix.eu/v1/refunds"

payload = {
    "payment_id": "pay_q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E",
    "amount": 1500,
    "merchant_reference": 3456789012,
    "reason": "Customer requested a refund"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    payment_id: 'pay_q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E',
    amount: 1500,
    merchant_reference: 3456789012,
    reason: 'Customer requested a refund'
  })
};

fetch('https://api.flowlix.eu/v1/refunds', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.flowlix.eu/v1/refunds",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'payment_id' => 'pay_q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E',
    'amount' => 1500,
    'merchant_reference' => 3456789012,
    'reason' => 'Customer requested a refund'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.flowlix.eu/v1/refunds"

	payload := strings.NewReader("{\n  \"payment_id\": \"pay_q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E\",\n  \"amount\": 1500,\n  \"merchant_reference\": 3456789012,\n  \"reason\": \"Customer requested a refund\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.flowlix.eu/v1/refunds")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"payment_id\": \"pay_q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E\",\n  \"amount\": 1500,\n  \"merchant_reference\": 3456789012,\n  \"reason\": \"Customer requested a refund\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.flowlix.eu/v1/refunds")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"payment_id\": \"pay_q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E\",\n  \"amount\": 1500,\n  \"merchant_reference\": 3456789012,\n  \"reason\": \"Customer requested a refund\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "ref_L9xQ4wE2rT8yU6iO3pA7sD1f",
  "payment_id": "pay_q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E",
  "amount": 1500,
  "currency": "EUR",
  "merchant_reference": 3456789012,
  "reason": "Customer requested a partial refund",
  "refund_type": "PARTIAL",
  "status": "PROCESSING",
  "created_at": 1719795600,
  "updated_at": 1719795660,
  "livemode": false
}

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 create call submits the Refund before responding. A 201 response therefore contains the Refund in PROCESSING, or already in terminal FAILED when submission was definitively rejected. Monitor a PROCESSING Refund via subsequent GET /v1/payments/{id} calls. It transitions to SUCCEEDED when confirmed or FAILED when it cannot be completed.

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 uses the Refund’s effective request identity: a retry with equivalent payment_id, amount, merchant_reference, and reason returns the original response, while a retry with the same key but a different identity is rejected with 409 and error.code: "idempotency_key_reused". Pick a deterministic key tied to the Refund operation and preserve its effective identity on retries.

POST

refunds

Create a refund

curl --request POST \
  --url https://api.flowlix.eu/v1/refunds \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "payment_id": "pay_q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E",
  "amount": 1500,
  "merchant_reference": 3456789012,
  "reason": "Customer requested a refund"
}
'

import requests

url = "https://api.flowlix.eu/v1/refunds"

payload = {
    "payment_id": "pay_q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E",
    "amount": 1500,
    "merchant_reference": 3456789012,
    "reason": "Customer requested a refund"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    payment_id: 'pay_q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E',
    amount: 1500,
    merchant_reference: 3456789012,
    reason: 'Customer requested a refund'
  })
};

fetch('https://api.flowlix.eu/v1/refunds', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.flowlix.eu/v1/refunds",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'payment_id' => 'pay_q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E',
    'amount' => 1500,
    'merchant_reference' => 3456789012,
    'reason' => 'Customer requested a refund'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.flowlix.eu/v1/refunds"

	payload := strings.NewReader("{\n  \"payment_id\": \"pay_q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E\",\n  \"amount\": 1500,\n  \"merchant_reference\": 3456789012,\n  \"reason\": \"Customer requested a refund\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.flowlix.eu/v1/refunds")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"payment_id\": \"pay_q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E\",\n  \"amount\": 1500,\n  \"merchant_reference\": 3456789012,\n  \"reason\": \"Customer requested a refund\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.flowlix.eu/v1/refunds")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"payment_id\": \"pay_q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E\",\n  \"amount\": 1500,\n  \"merchant_reference\": 3456789012,\n  \"reason\": \"Customer requested a refund\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "ref_L9xQ4wE2rT8yU6iO3pA7sD1f",
  "payment_id": "pay_q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E",
  "amount": 1500,
  "currency": "EUR",
  "merchant_reference": 3456789012,
  "reason": "Customer requested a partial refund",
  "refund_type": "PARTIAL",
  "status": "PROCESSING",
  "created_at": 1719795600,
  "updated_at": 1719795660,
  "livemode": false
}

Authorizations

Authorization

string

header

required

Use the secret API key for the intended merchant and mode as the Bearer token. Sandbox keys start with api_test_sk_. Send the key only from your server environment.

Authorization: Bearer api_test_sk_abc123def456

Headers

Idempotency-Key

string

required

A unique key to ensure one effective operation is processed only once. If the same key and an equivalent operation-specific effective request identity have already completed successfully, the original response is returned. A different identity returns 409 idempotency_key_reused. Non-2xx responses are not cached, so callers may retry after errors. No fixed retention period is promised by this contract.

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. Minor units follow that currency's ISO 4217 exponent, so 4999 is EUR 49.99 (exponent 2) but JPY 4999 (exponent 0). Do not assume two decimal places. Use the remaining refundable amount for a full refund.

Required range: x >= 1

Example:

1500

reason

string

required

Merchant-provided refund reason. The API accepts at most 50 characters.

Required string length: 1 - 50

Example:

"Full refund verification"

merchant_reference

integer<int64>

Optional merchant-side reconciliation reference. The value must contain exactly 10 decimal digits and does not provide idempotency by itself.

Required range: 1000000000 <= x <= 9999999999

Example:

1234567890

Response

Refund created and submitted. Inspect the returned status: continue retrieval through the parent Payment for PROCESSING, or handle the nested failure when the Refund is already FAILED.

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 the currency's minor units, per its ISO 4217 exponent: 4999 is EUR 49.99 but JPY 4999.

Required range: x >= 1

Example:

1500

currency

string

required

Canonical uppercase three-letter ISO 4217 currency code. Responses always return the original currency the payment was created in; a provider response never replaces it.

Required string length: 3

Pattern: ^[A-Z]{3}$

Example:

"EUR"

reason

string

required

Merchant-provided refund reason stored with the refund.

Maximum string length: 50

Example:

"Full refund verification"

refund_type

enum<string>

required

Whether the refund covers the full original payment amount or only part of it.

Available options:

FULL,

PARTIAL

Example:

"FULL"

status

enum<string>

required

Current refund lifecycle status. Refunds normally move from PENDING to PROCESSING, then to SUCCEEDED or FAILED.

Available options:

PENDING,

PROCESSING,

SUCCEEDED,

FAILED

Example:

"PENDING"

created_at

integer<int64>

required

Unix timestamp when the refund was created.

Example:

1719795600

updated_at

integer<int64>

required

Unix timestamp when the refund was last updated.

Example:

1719795660

livemode

boolean

required

Always false for a Refund created in Sandbox.

Example:

false

merchant_reference

integer<int64> | null

Merchant-side reconciliation reference for this refund, if provided.

Required range: 1000000000 <= x <= 9999999999

Example:

1234567890

failure

object | null

Refund failure details when the refund reaches FAILED.

Show child attributes

completed_at

integer<int64> | null

Unix timestamp when the refund reached a terminal status.

Example:

1719799200

⌘I

Get started

Build with Flowlix

Handle failures

API reference

Create a refund

Idempotency

Authorizations

Headers

Body

Response