Reconciliation

Verify Fynex settlement records against your own books using the GraphQL reconciliation queries.

The Fynex reconciliation surface lets sellers compare what Fynex has recorded as settled funds against what actually arrived in their bank account. Each reconciliation record represents a settlement deposit event with three amounts: reported (what the processor claimed), expected (what Fynex calculated), and actual (what was received).

Note

GraphQL only — cookie session required. All reconciliation queries are on POST /dashboard/graphql and require permission RECONCILIATIONS_READ on the session. See GraphQL Authentication.

Use cases

• Daily settlement file matching — pull all reconciliation records for the previous day and compare reported vs actual amounts to detect shortfalls.
• Dispute investigation — fetch a single reconciliation(id) to see the full fact list (fees reported vs expected) for a specific deposit event.
• Dispute reserve calculation — use reconciliationStatistics to get aggregate counts of pending, successful, and discrepancy records over a date range.

GraphQL operations

Note

Raw processor-side settlement records (the underlying settlement file contents) are not part of the seller-facing API. Their shape follows whichever processor is configured for the seller, so the field names are not a stable public contract and are not suitable to build against. The reconciliation surfaces documented on this page are the supported way to reconcile.

Type reference

ReconciliationConnection

The list query returns a connection type rather than a plain array:

ReconciliationSettlementDeposit

The primary reconciliation entity — one record per settlement deposit event.

ReconciliationSettlementReport

ReconciliationFact

Each fact represents a single line-item discrepancy found during reconciliation.

ReconciliationStatistics

Code samples

curl

# Step 1 — login
curl -sc cookies.txt \
  -X POST https://api.fynex.ai/api/v1/login/dashboard \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your_password"}'

# Step 2 — list reconciliations for a date range
curl -b cookies.txt \
  -X POST https://api.fynex.ai/dashboard/graphql \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query Recons($dateFrom: Time, $dateTo: Time, $limit: Int, $offset: Int) { reconciliations(dateFrom: $dateFrom, dateTo: $dateTo, limit: $limit, offset: $offset) { totalCount items { id status depositAmountReported depositAmountExpected depositAmountActual bankingTransferReference createdAt } } }",
    "variables": {
      "dateFrom": "2025-01-01T00:00:00Z",
      "dateTo": "2025-01-31T23:59:59Z",
      "limit": 50,
      "offset": 0
    }
  }'

JavaScript

const BASE = 'https://api.fynex.ai';

async function login(email, password) {
  const res = await fetch(`${BASE}/api/v1/login/dashboard`, {
    method: 'POST',
    credentials: 'include',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ email, password }),
  });
  if (!res.ok) throw new Error(`Login failed: ${res.status}`);
}

async function gql(query, variables = {}) {
  const res = await fetch(`${BASE}/dashboard/graphql`, {
    method: 'POST',
    credentials: 'include',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ query, variables }),
  });
  const { data, errors } = await res.json();
  if (errors?.length) throw new Error(errors[0].message);
  return data;
}

await login('you@example.com', 'your_password');

const { reconciliations } = await gql(
  `query Recons($dateFrom: Time, $dateTo: Time, $limit: Int, $offset: Int) {
     reconciliations(dateFrom: $dateFrom, dateTo: $dateTo, limit: $limit, offset: $offset) {
       totalCount
       items {
         id
         status
         depositAmountReported
         depositAmountExpected
         depositAmountActual
         bankingTransferReference
         createdAt
         facts {
           factType
           discrepancyPlace
           feeAmountReported
           feeAmountExpected
         }
       }
     }
   }`,
  {
    dateFrom: '2025-01-01T00:00:00Z',
    dateTo: '2025-01-31T23:59:59Z',
    limit: 50,
    offset: 0,
  }
);

console.log(`Total: ${reconciliations.totalCount}`);
for (const r of reconciliations.items) {
  const diff = r.depositAmountActual - r.depositAmountExpected;
  console.log(`${r.id} [${r.status}] diff: ${diff.toFixed(2)}`);
}

Python

import requests

BASE = "https://api.fynex.ai"
session = requests.Session()

session.post(
    f"{BASE}/api/v1/login/dashboard",
    json={"email": "you@example.com", "password": "your_password"},
).raise_for_status()

query = """
  query Recons($dateFrom: Time, $dateTo: Time, $limit: Int, $offset: Int) {
    reconciliations(
      dateFrom: $dateFrom
      dateTo: $dateTo
      limit: $limit
      offset: $offset
    ) {
      totalCount
      items {
        id
        status
        depositAmountReported
        depositAmountExpected
        depositAmountActual
        bankingTransferReference
        createdAt
        facts {
          factType
          discrepancyPlace
          feeAmountReported
          feeAmountExpected
          feeAmountActual
        }
      }
    }
  }
"""

resp = session.post(
    f"{BASE}/dashboard/graphql",
    json={
        "query": query,
        "variables": {
            "dateFrom": "2025-01-01T00:00:00Z",
            "dateTo": "2025-01-31T23:59:59Z",
            "limit": 50,
            "offset": 0,
        },
    },
)
resp.raise_for_status()
result = resp.json()
if "errors" in result:
    raise RuntimeError(result["errors"][0]["message"])

data = result["data"]["reconciliations"]
print(f"Total records: {data['totalCount']}")

for r in data["items"]:
    diff = r["depositAmountActual"] - r["depositAmountExpected"]
    print(f"ID {r['id']} [{r['status']}]: diff={diff:+.2f}, ref={r['bankingTransferReference']}")
    if r["facts"]:
        for fact in r["facts"]:
            print(f"  Fact: {fact['factType']} @ {fact['discrepancyPlace']}")

Reconciliation workflow

1. Fetch daily statistics with reconciliationStatistics(dateFrom, dateTo) to get a quick health check: successCount, pendingCount, and discrepancyCount.

2. List pending and discrepancy records by passing status: "pending" or status: "discrepancy" to reconciliations. Focus your investigation on these.

3. Inspect a specific record with reconciliation(id) to get the full facts list showing where fees diverge between reported, expected, and actual.

4. Cross-reference with wallet entries — each settled payment that contributed to the deposit will have a corresponding WalletEntry with kind: INCOMING_PAYMENT_PROCESSED. Compare depositAmountActual against the sum of wallet credit entries for the same period.

5. Escalate discrepancies to your Fynex account manager if depositAmountActual differs from depositAmountExpected and the facts list does not explain the gap.

Filtering tips

• dateFrom and dateTo accept RFC 3339 timestamps (2025-01-15T00:00:00Z).
• Use status to filter by reconciliation outcome. Common values include pending, success, and discrepancy — confirm the exact values with your Fynex contact as the list may expand.
• Combine limit + offset for pagination. The totalCount field tells you how many pages to expect.

See also

• GraphQL Authentication — Obtain the dashboard_session cookie required for all GraphQL calls.
• Wallets — Inspect wallet ledger entries that correspond to reconciled settlements.
• Payment Lifecycle — Understand the status transitions a payment goes through before it settles.