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,
  "merchant_reference": 3456789012,
  "reason": "Customer requested a refund"
}
'

import requests

url = "https://api.flowlix.dev/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.dev/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.dev/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.dev/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.dev/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.dev/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",
  "reason": "Full refund verification",
  "refund_type": "FULL",
  "status": "PENDING",
  "created_at": 1719795600,
  "updated_at": 1719795660,
  "livemode": false,
  "merchant_reference": 1234567890,
  "failure": {
    "code": "fraud_filter",
    "message": "The payment was declined by fraud controls."
  },
  "completed_at": 1719799200
}

{
  "error": {
    "message": "One or more request parameters failed validation.",
    "code": "parameter_invalid",
    "param": "payment_method_data[card][number]",
    "doc_url": "https://docs.flowlix.dev",
    "request_id": "req_abc123def456"
  }
}

{
  "error": {
    "message": "One or more request parameters failed validation.",
    "code": "parameter_invalid",
    "param": "payment_method_data[card][number]",
    "doc_url": "https://docs.flowlix.dev",
    "request_id": "req_abc123def456"
  }
}

{
  "error": {
    "message": "One or more request parameters failed validation.",
    "code": "parameter_invalid",
    "param": "payment_method_data[card][number]",
    "doc_url": "https://docs.flowlix.dev",
    "request_id": "req_abc123def456"
  }
}

{
  "error": {
    "message": "One or more request parameters failed validation.",
    "code": "parameter_invalid",
    "param": "payment_method_data[card][number]",
    "doc_url": "https://docs.flowlix.dev",
    "request_id": "req_abc123def456"
  }
}

{
  "error": {
    "message": "One or more request parameters failed validation.",
    "code": "parameter_invalid",
    "param": "payment_method_data[card][number]",
    "doc_url": "https://docs.flowlix.dev",
    "request_id": "req_abc123def456"
  }
}

{
  "error": {
    "message": "One or more request parameters failed validation.",
    "code": "parameter_invalid",
    "param": "payment_method_data[card][number]",
    "doc_url": "https://docs.flowlix.dev",
    "request_id": "req_abc123def456"
  }
}

{
  "error": {
    "message": "One or more request parameters failed validation.",
    "code": "parameter_invalid",
    "param": "payment_method_data[card][number]",
    "doc_url": "https://docs.flowlix.dev",
    "request_id": "req_abc123def456"
  }
}

{
  "error": {
    "message": "One or more request parameters failed validation.",
    "code": "parameter_invalid",
    "param": "payment_method_data[card][number]",
    "doc_url": "https://docs.flowlix.dev",
    "request_id": "req_abc123def456"
  }
}

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 when the refund is 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 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, amount, or merchant_reference, is rejected with 409 and error.code: "idempotency_key_reused". 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,
  "merchant_reference": 3456789012,
  "reason": "Customer requested a refund"
}
'

import requests

url = "https://api.flowlix.dev/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.dev/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.dev/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.dev/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.dev/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.dev/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",
  "reason": "Full refund verification",
  "refund_type": "FULL",
  "status": "PENDING",
  "created_at": 1719795600,
  "updated_at": 1719795660,
  "livemode": false,
  "merchant_reference": 1234567890,
  "failure": {
    "code": "fraud_filter",
    "message": "The payment was declined by fraud controls."
  },
  "completed_at": 1719799200
}

{
  "error": {
    "message": "One or more request parameters failed validation.",
    "code": "parameter_invalid",
    "param": "payment_method_data[card][number]",
    "doc_url": "https://docs.flowlix.dev",
    "request_id": "req_abc123def456"
  }
}

{
  "error": {
    "message": "One or more request parameters failed validation.",
    "code": "parameter_invalid",
    "param": "payment_method_data[card][number]",
    "doc_url": "https://docs.flowlix.dev",
    "request_id": "req_abc123def456"
  }
}

{
  "error": {
    "message": "One or more request parameters failed validation.",
    "code": "parameter_invalid",
    "param": "payment_method_data[card][number]",
    "doc_url": "https://docs.flowlix.dev",
    "request_id": "req_abc123def456"
  }
}

{
  "error": {
    "message": "One or more request parameters failed validation.",
    "code": "parameter_invalid",
    "param": "payment_method_data[card][number]",
    "doc_url": "https://docs.flowlix.dev",
    "request_id": "req_abc123def456"
  }
}

{
  "error": {
    "message": "One or more request parameters failed validation.",
    "code": "parameter_invalid",
    "param": "payment_method_data[card][number]",
    "doc_url": "https://docs.flowlix.dev",
    "request_id": "req_abc123def456"
  }
}

{
  "error": {
    "message": "One or more request parameters failed validation.",
    "code": "parameter_invalid",
    "param": "payment_method_data[card][number]",
    "doc_url": "https://docs.flowlix.dev",
    "request_id": "req_abc123def456"
  }
}

{
  "error": {
    "message": "One or more request parameters failed validation.",
    "code": "parameter_invalid",
    "param": "payment_method_data[card][number]",
    "doc_url": "https://docs.flowlix.dev",
    "request_id": "req_abc123def456"
  }
}

{
  "error": {
    "message": "One or more request parameters failed validation.",
    "code": "parameter_invalid",
    "param": "payment_method_data[card][number]",
    "doc_url": "https://docs.flowlix.dev",
    "request_id": "req_abc123def456"
  }
}

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

string

required

Merchant-provided refund reason passed to the payment provider as the refund comment. Limited to 50 characters by WhiteLark.

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 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

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

Whether this refund was created using a live API key.

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

Retrieve a payment

⌘I

Get started

Guides

Error handling

Payments API

Create a refund

Idempotency

Authorizations

Headers

Body

Response