Refunds

​

Create a refund

curl -X POST https://api.flowlix.dev/v1/refunds \
  -H "Authorization: Bearer api_test_sk_abc123def456" \
  -H "Idempotency-Key: refund-ord_1234-1" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_id": "pay_q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E",
    "amount": 1500,
    "merchant_reference": 3456789012,
    "reason": "Customer requested a refund"
  }'

• amount is always required, in minor units. For a full refund, send the payment’s current amount_refundable.
• merchant_reference is optional, belongs to this refund, and must be an integer with exactly 10 digits (from 1000000000 to 9999999999).
• reason is required free text for your support and audit trail.
• A payment can be refunded multiple times until the accumulated refunded amount reaches the original amount. A refund that would exceed amount_refundable is rejected with 422 and error.code: "amount_exceeds_refundable".

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

​

Refund lifecycle

​

Idempotent refunds

• Retrying with the same key and the same body returns the original refund — it is safe to retry on timeouts.
• Reusing a key with any field changed (a different amount, reason, or merchant_reference) is rejected with 409 and error.code: "idempotency_key_reused".
• Retrying while the original request is still processing returns 409 with error.code: "idempotency_key_in_use"; wait briefly and retry the same body.

​

Operational notes

• Refunds can take several business days to appear on the customer’s statement, even after SUCCEEDED.
• If a refund FAILED (for example the card account was closed), resolve it with the customer through another channel; creating the same refund again will typically fail for the same reason.