`get_finance_clawbacks_by_id`

Read-only

Calls GET /api/finance/clawbacks/{id} as the signed-in person · REST reference

One payout clawback with its recovery legs (platform staff)

The clawback as the queue reads it, its recovery legs oldest first, what is still owed, the clinic's Stripe balance as Stripe last reported it, and whether executing it needs the payout's transfer id given. Reads only. Money is integer CENTS; times are epoch milliseconds.

Arguments

Argument	Type		Description
`id`path	string (uuid)	required

Example call

A client sends this over the MCP session; Claude and other agents build it for you. The values are placeholders — the shape is real.

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_finance_clawbacks_by_id",
    "arguments": {
      "id": "11111111-1111-4111-8111-111111111111"
    }
  }
}

Result

On success (HTTP 200) the tool returns one text item holding the API's JSON, pretty-printed.

The clawback's detail

json

{
  "clawback": {
    "amount": 1,
    "approvedAt": 1,
    "approvedBy": "11111111-1111-4111-8111-111111111111",
    "creditedAmount": 1,
    "currency": "string",
    "deniedAt": 1,
    "deniedBy": "11111111-1111-4111-8111-111111111111",
    "feeCents": 1,
    "feeLiability": {},
    "feeWaiverConsumed": true,
    "filedBy": "SERVICE_PROVIDER",
    "id": "11111111-1111-4111-8111-111111111111",
    "initiatedBy": "11111111-1111-4111-8111-111111111111",
    "initiatorOrgId": "11111111-1111-4111-8111-111111111111"
  },
  "connectBalance": 1,
  "connectBalanceAt": 1,
  "legs": [
    {
      "amount": 1,
      "clawbackId": "11111111-1111-4111-8111-111111111111",
      "confirmed": true,
      "confirmedAt": 1,
      "createdAt": 1,
      "currency": "string",
      "id": "11111111-1111-4111-8111-111111111111",
      "kind": "REVERSAL",
      "postedAt": 1,
      "reference": "string",
      "returned": true,
      "returnedAt": 1,
      "status": "string",
      "stripeEventId": "string"
    }
  ],
  "needsTransferId": true,
  "owedCents": 1
}

Fields

Field	Type	Description
`clawback`	object	A clawback as the platform review queue reads it — with how often Pawsitive Future has absorbed the clinic's fees before, and how its notice, reversal and recovery stand.
`clawback.amount`	integer	CENTS asked back — at most `creditedAmount`.
`clawback.approvedAt`	integer \| null
`clawback.approvedBy`	string (uuid) \| null
`clawback.creditedAmount`	integer	CENTS the voucher's approval credited — what its payout paid.
`clawback.currency`	string
`clawback.deniedAt`	integer \| null
`clawback.deniedBy`	string (uuid) \| null
`clawback.feeCents`	integer	CENTS of recovery fee assessed; 0 until a fee is realized.
`clawback.feeLiability`	object \| null	Proposed when Pawsitive Future files the clawback, set by an approval; null on a clinic's filing until it is approved, and on a denial.
`clawback.feeWaiverConsumed`	boolean	Whether Pawsitive Future absorbs this approved clawback's processing cost.
`clawback.filedBy`	"SERVICE_PROVIDER" \| "PAWSITIVE_FUTURE"	Who filed a clawback — the service provider that was paid, or Pawsitive Future staff.
`clawback.id`	string (uuid)	The clawback's ledger transaction.
`clawback.initiatedBy`	string (uuid) \| null	The user who filed it.
`clawback.initiatorOrgId`	string (uuid) \| null	The service provider that filed it; null when Pawsitive Future did.
`clawback.memo`	string \| null
`clawback.orgId`	string (uuid)	The service provider the payout went to.
`clawback.orgName`	string \| null
`clawback.paidAt`	integer \| null	Epoch milliseconds the voucher was paid out.
`clawback.payoutStripeTransferId`	string \| null	That payout's Stripe transfer (`tr_…`), when it recorded one.
`clawback.payoutTransactionId`	string (uuid) \| null	The org's PAYOUT settlement created at the voucher's `paidAt`; null when none matches.
`clawback.reasonCode`	"PFF_DISCRETIONARY" \| "PROCEDURE_NOT_COMPLETED" \| "BENEFICIARY_DISPUTE" \| "DUPLICATE_OR_ERRONEOUS_PAYOUT" \| "DONATION_REVERSED" \| "OTHER"	Why a clawback was filed. A service provider files PROCEDURE_NOT_COMPLETED, BENEFICIARY_DISPUTE or OTHER about a payout it received; the rest are Pawsitive Future's findings. OTHER needs a memo of at least 20 characters.
`clawback.requestedAt`	integer	Epoch milliseconds.
`clawback.status`	"REQUESTED" \| "APPROVED" \| "DENIED" \| "EXECUTING" \| "RECOVERED" \| "PARTIALLY_RECOVERED" \| … (7 values)	A payout clawback's lifecycle, kept apart from its ledger transaction's status. Filing and deciding reach REQUESTED, APPROVED and DENIED; the rest follow execution. RECOVERED is "cash confirmed": Pawsitive Future has confirmed the full amount is back in hand, never merely a booked reversal.
`clawback.transferReversalState`	object \| null
`clawback.voucherCode`	string
`clawback.voucherId`	string (uuid)
`clawback.voucherValueReversed`	boolean \| null	Decided at approval, beside the money: whether the voucher stops counting as help delivered once the clawback resolves. Null until approved, and on a denial.
`clawback.voucherValueReversedByDefault`	boolean \| null	What an approval records as `voucherValueReversed` when the approver does not say — set by the reason: true for PROCEDURE_NOT_COMPLETED, BENEFICIARY_DISPUTE and DUPLICATE_OR_ERRONEOUS_PAYOUT, false for DONATION_REVERSED. Null for PFF_DISCRETIONARY and OTHER, which have no default: an approval must say.
`clawback.cashConfirmationSource`	string \| null	The kinds of recovery the confirmed cash came by, comma-joined.
`clawback.cashConfirmedAt`	integer \| null	When the full amount was confirmed back — what RECOVERED means.
`clawback.noticeMessageId`	string \| null
`clawback.noticeSentAt`	integer \| null	When the service provider was sent the written notice. Null after an approval means the notice did not send: nothing is recovered, payouts are paused, and POST /api/finance/clawbacks/{id}/execute retries it.
`clawback.offsetPendingAmount`	integer	CENTS its offset payouts have moved that no OFFSET leg has recorded yet — settled, the transfer not confirmed. A failed one stays counted until the reconcile records it or it is released (POST /api/finance/clawbacks/{id}/offsets/{payoutTransactionId}/release).
`clawback.originalStripeTransferId`	string \| null	The payout transfer (`tr_…`) the reversal reverses.
`clawback.outstandingAmount`	integer	CENTS still owed while it is being collected (APPROVED, EXECUTING); 0 once closed.
`clawback.pausesPayouts`	boolean	Whether this clawback pauses its service provider's payouts: APPROVED or EXECUTING, or PARTIALLY_RECOVERED / WRITTEN_OFF until payouts are resumed.
`clawback.payoutsResumedAt`	integer \| null
`clawback.payoutsResumedBy`	string (uuid) \| null
`clawback.payoutsResumedReason`	string \| null
`clawback.recoveredAmount`	integer	CENTS recovered so far — its confirmed recovery legs.
`clawback.stripeReversalId`	string \| null	The transfer reversal (`trr_…`), once booked.
`clawback.transferReversalLastError`	string \| null	The last failed reversal attempt's error; null once one succeeds.
`clawback.transferReversalUpdatedAt`	integer \| null	Epoch milliseconds the reversal outbox state was last written; null when none was. A PENDING older than two minutes is read as a reversal whose synchronous call died.
`clawback.writtenOffAt`	integer \| null
`clawback.writtenOffBy`	string (uuid) \| null
`clawback.writtenOffMemo`	string \| null
`clawback.feesAbsorbedBefore`	integer	How many of the service provider's other approved clawbacks Pawsitive Future absorbed the processing cost of — what the approver weighs for a repeat.
`connectBalance`	integer \| null	The clinic's Stripe balance as Stripe last reported it, CENTS, signed — negative while a reversal is uncovered. Null when none was recorded.
`connectBalanceAt`	integer \| null
`legs`	array of object	Its recovery legs, oldest first.
`legs[].amount`	integer	CENTS.
`legs[].clawbackId`	string (uuid)
`legs[].confirmed`	boolean	Whether it is cash.
`legs[].confirmedAt`	integer \| null
`legs[].createdAt`	integer
`legs[].currency`	string
`legs[].id`	string (uuid)
`legs[].kind`	"REVERSAL" \| "OFFSET" \| "BANK_DEBIT" \| "OUT_OF_BAND" \| "CLINIC_PAYMENT"
`legs[].postedAt`	integer \| null	When the money moved.

More fields follow; the REST reference lists them all.

When it fails

A failed call returns isError: true with the API's message as text.

403: Authenticated, but the caller holds none of the required permissions.
404: No such clawback.

What the model is shown

This is the tool exactly as the server lists it in tools/list. The description starts with the REST call it makes.

json

{
  "name": "get_finance_clawbacks_by_id",
  "description": "GET /api/finance/clawbacks/{id} — The clawback as the queue reads it, its recovery legs oldest first, what is still owed, the clinic's Stripe balance as Stripe last reported it, and whether executing it needs the payout's transfer id given. Reads only. Money is integer CENTS; times are epoch milliseconds.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string"
      }
    },
    "required": [
      "id"
    ]
  },
  "annotations": {
    "readOnlyHint": true,
    "openWorldHint": false
  }
}