POST /v1/refund

Refunds the full amount of a captured payment. Partial refunds are not available in V1. See the Refund guide for the narrative version.

Request

POST /v1/refund HTTP/1.1
Host: api.sandbox.settleflow.io
Content-Type: application/json
epro-api-key: pk_test_...

E-PRO compatibility. POST /v1/refund/direct is also accepted (alias), as is a application/x-www-form-urlencoded body. See Migration.

Body

Provide one of the following identifiers. When both are sent, Reference wins.

Field	Type	Description
`Reference`	string	The payment request ID returned from `/v1/payment/direct`.
`Tid`	string	Your own transaction reference from the original payment.

Success response

{
  "Code": 0,
  "Result": {
    "OperationType": "refund",
    "Status": "captured",
    "Tid": "order-2026-001",
    "Reference": "ref_xyz789",
    "Amount": "49.99",
    "UserId": "customer-42",
    "Message": "Payment refunded",
    "Date": "2026-04-23 09:12:03"
  }
}

Result fields

Field	Type	Description
`OperationType`	string	Always `"refund"`.
`Status`	string	`captured` on success, `failed` otherwise.
`Tid`	string	Your original transaction reference.
`Reference`	string	The refund ID (distinct from the payment `Reference`).
`Amount`	number	Refunded amount in major currency units.
`UserId`	string	`Uid` supplied on the original payment.
`Message`	string	Human-readable outcome.
`Date`	string	`YYYY-MM-DD HH:mm:ss` (UTC).

Error response

{ "Code": 102, "Error": "Transaction not found" }

Code	Meaning
`1`	Neither `Tid` nor `Reference` supplied
`3`	Invalid API key
`4`	API key missing
`102`	Transaction not found
`103`	Invalid transaction (e.g. already refunded, not captured)

Full list on Error codes.

Examples

cURL

curl -X POST https://api.sandbox.settleflow.io/v1/refund \
  -H "epro-api-key: pk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "Reference": "pr_abc123" }'

Node.js

const res = await fetch("https://api.sandbox.settleflow.io/v1/refund", {
  method: "POST",
  headers: {
    "epro-api-key": process.env.SETTLEFLOW_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ Reference: "pr_abc123" }),
});
const { Code, Result, Error: errMsg } = await res.json();
if (Code !== 0) throw new Error(`[${Code}] ${errMsg}`);

PHP

<?php
$ch = curl_init('https://api.sandbox.settleflow.io/v1/refund');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'epro-api-key: ' . getenv('SETTLEFLOW_API_KEY'),
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode(['Reference' => 'pr_abc123']),
]);
$body = json_decode(curl_exec($ch), true);
if ($body['Code'] !== 0) {
    throw new \RuntimeException("[{$body['Code']}] {$body['Error']}");
}

Notes

Refunds are idempotent against the source payment — a second call returns 103.
A REFUND_SUCCEEDED webhook is delivered to your configured webhook endpoint. See Webhooks.

On this page