POST /v1/status/direct

Returns the latest state of a payment. Useful after a 3DS redirect or for reconciliation. See the Status guide for the narrative version.

Request

POST /v1/status/direct HTTP/1.1
Host: api.settleflow.io
Content-Type: application/json
epro-api-key: sk_test_...

Body

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

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

Success response

{
  "Code": 0,
  "Result": {
    "OperationType": "payment",
    "Status": "captured",
    "Tid": "order-2026-001",
    "Reference": "pr_abc123",
    "Amount": 49.99,
    "UserId": "customer-42",
    "Message": "Payment was successful",
    "Date": "2026-04-22 14:30:45"
  }
}

Result fields

Field	Type	Description
`OperationType`	enum	`payment`, `refund`, `credit`.
`Status`	enum	`authorized`, `captured`, `failed`, `cancelled`, `pending`, `rejected_pw`.
`Tid`	string	Your transaction reference.
`Reference`	string	SettleFlow identifier.
`Amount`	number	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

Full list on Error codes.

Examples

cURL

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

Node.js

const res = await fetch("https://api.settleflow.io/v1/status/direct", {
  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}`);
// Result.Status → "captured" | "authorized" | "pending" | "failed" | ...

PHP

<?php
$ch = curl_init('https://api.settleflow.io/v1/status/direct');
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

Status is authoritative for reconciliation, but webhooks remain the preferred real-time channel. See Webhooks.
Do not poll in tight loops. A bounded retry after a 3DS redirect is illustrated on the status guide.

On this page