`post_finance_clawbacks_by_id_recoveries`

Changes data · you confirm first

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

Record a repayment received outside Stripe (platform staff)

Records an OUT_OF_BAND recovery leg — cash at once — and resolves the clawback RECOVERED when its confirmed legs reach the amount. Also for a contest Pawsitive Future lost: the restored amount is recorded as a repayment. When the clinic's Stripe balance is negative, the same amount (up to zero) is transferred into it, so Stripe does not also debit the clinic's bank. Refused past what the clawback is still owed (409); a second leg with the same reference and amount writes nothing.

Arguments

Argument	Type		Description
`id`path	string (uuid)	required
`body`JSON	object	required	The request body, as a JSON object. Its fields are listed below.

Fields of `body`

Field	Type		Description
`amount`	integer	required	CENTS received.
`receivedAt`	integer	required	Epoch milliseconds the money was received; not in the future.
`reference`	string	required	The receipt's reference — a check number, a wire id.

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": "post_finance_clawbacks_by_id_recoveries",
    "arguments": {
      "id": "11111111-1111-4111-8111-111111111111",
      "body": {
        "amount": 1,
        "receivedAt": 1,
        "reference": "string"
      }
    }
  }
}

Confirmation

The client shows the person the exact request and waits. Nothing runs until they tick Make this change. See Reading and changing.

Result

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

The clawback's detail after the repayment

json

{
  "clawback": {
    "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": [
      {}
    ],
    "needsTransferId": true,
    "owedCents": 1
  },
  "recovered": true,
  "topUpTransferId": "string"
}

Fields

Field	Type	Description
`clawback`	object	One clawback with everything its detail drawer shows.
`clawback.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.clawback.amount`	integer	CENTS asked back — at most `creditedAmount`.
`clawback.clawback.approvedAt`	integer \| null
`clawback.clawback.approvedBy`	string (uuid) \| null
`clawback.clawback.creditedAmount`	integer	CENTS the voucher's approval credited — what its payout paid.
`clawback.clawback.currency`	string
`clawback.clawback.deniedAt`	integer \| null
`clawback.clawback.deniedBy`	string (uuid) \| null
`clawback.clawback.feeCents`	integer	CENTS of recovery fee assessed; 0 until a fee is realized.
`clawback.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.clawback.feeWaiverConsumed`	boolean	Whether Pawsitive Future absorbs this approved clawback's processing cost.
`clawback.clawback.filedBy`	"SERVICE_PROVIDER" \| "PAWSITIVE_FUTURE"	Who filed a clawback — the service provider that was paid, or Pawsitive Future staff.
`clawback.clawback.id`	string (uuid)	The clawback's ledger transaction.
`clawback.clawback.initiatedBy`	string (uuid) \| null	The user who filed it.
`clawback.clawback.initiatorOrgId`	string (uuid) \| null	The service provider that filed it; null when Pawsitive Future did.
`clawback.clawback.memo`	string \| null
`clawback.clawback.orgId`	string (uuid)	The service provider the payout went to.
`clawback.clawback.orgName`	string \| null
`clawback.clawback.paidAt`	integer \| null	Epoch milliseconds the voucher was paid out.
`clawback.clawback.payoutStripeTransferId`	string \| null	That payout's Stripe transfer (`tr_…`), when it recorded one.
`clawback.clawback.payoutTransactionId`	string (uuid) \| null	The org's PAYOUT settlement created at the voucher's `paidAt`; null when none matches.
`clawback.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.clawback.requestedAt`	integer	Epoch milliseconds.
`clawback.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.clawback.transferReversalState`	object \| null
`clawback.clawback.voucherCode`	string
`clawback.clawback.voucherId`	string (uuid)
`clawback.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.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.clawback.cashConfirmationSource`	string \| null	The kinds of recovery the confirmed cash came by, comma-joined.
`clawback.clawback.cashConfirmedAt`	integer \| null	When the full amount was confirmed back — what RECOVERED means.
`clawback.clawback.noticeMessageId`	string \| null
`clawback.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.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.clawback.originalStripeTransferId`	string \| null	The payout transfer (`tr_…`) the reversal reverses.
`clawback.clawback.outstandingAmount`	integer	CENTS still owed while it is being collected (APPROVED, EXECUTING); 0 once closed.
`clawback.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.clawback.payoutsResumedAt`	integer \| null
`clawback.clawback.payoutsResumedBy`	string (uuid) \| null
`clawback.clawback.payoutsResumedReason`	string \| null
`clawback.clawback.recoveredAmount`	integer	CENTS recovered so far — its confirmed recovery legs.
`clawback.clawback.stripeReversalId`	string \| null	The transfer reversal (`trr_…`), once booked.
`clawback.clawback.transferReversalLastError`	string \| null	The last failed reversal attempt's error; null once one succeeds.
`clawback.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.clawback.writtenOffAt`	integer \| null
`clawback.clawback.writtenOffBy`	string (uuid) \| null
`clawback.clawback.writtenOffMemo`	string \| null
`clawback.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.
`clawback.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.
`clawback.connectBalanceAt`	integer \| null
`clawback.legs`	array of object	Its recovery legs, oldest first.
`clawback.legs[].amount`	integer	CENTS.
`clawback.legs[].clawbackId`	string (uuid)
`clawback.legs[].confirmed`	boolean	Whether it is cash.
`clawback.legs[].confirmedAt`	integer \| null
`clawback.legs[].createdAt`	integer
`clawback.legs[].currency`	string
`clawback.legs[].id`	string (uuid)
`clawback.legs[].kind`	"REVERSAL" \| "OFFSET" \| "BANK_DEBIT" \| "OUT_OF_BAND" \| "CLINIC_PAYMENT"

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. A change the person declines, or lets time out, also comes back this way and nothing changes.

400: The request was malformed or failed a guard.
403: Authenticated, but the caller holds none of the required permissions.
404: No such clawback.
409: More than the clawback is still owed, a reference already recorded for another amount, or a clawback not being collected. Carries the DAL's sentence.

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": "post_finance_clawbacks_by_id_recoveries",
  "description": "POST /api/finance/clawbacks/{id}/recoveries — Records an OUT_OF_BAND recovery leg — cash at once — and resolves the clawback RECOVERED when its confirmed legs reach the amount. Also for a contest Pawsitive Future lost: the restored amount is recorded as a repayment. When the clinic's Stripe balance is negative, the same amount (up to zero) is transferred into it, so Stripe does not also debit the clinic's bank. Refused past what the clawback is still owed (409); a second leg with the same reference and amount writes nothing.\n\nThis changes data. The person is asked to confirm it before it runs, and nothing happens if they decline.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string"
      },
      "body": {
        "type": "string",
        "description": "The JSON request body: { amount*: integer (CENTS received.); receivedAt*: integer (Epoch milliseconds the money was received; not in the future.); reference*: string (The receipt's reference — a check number, a wire id.) }"
      }
    },
    "required": [
      "id",
      "body"
    ]
  },
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": true,
    "idempotentHint": false,
    "openWorldHint": false
  }
}

post_finance_clawbacks_by_id_recoveries

Arguments

Fields of body

Example call

Result

Fields

When it fails

`post_finance_clawbacks_by_id_recoveries`

Fields of `body`