`post_finance_clawbacks_by_id_execute`

Changes data · you confirm first

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

Send an approved clawback's notice if it has not been, then execute it (platform staff)

The retry for an approval whose notice or execution did not finish. Sends the written notice when noticeSentAt is null (nothing is recovered before it — 409 CLAWBACK_NOTICE_NOT_SENT when it still cannot be sent), then reverses the payout's Stripe transfer by what is still owed, records what the clinic's Stripe balance covered, and offsets credit the clinic holds. A reversal already booked is not repeated; a reversal Stripe refuses is recorded FAILED and answered 200 with error, so it can be executed again. PFF_DISCRETIONARY recovers by offset only. When the payout names no transfer (needsTransferId), give it as originalStripeTransferId.

Arguments

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

Fields of `body`

Field	Type		Description
`originalStripeTransferId`	string \| null		The payout's Stripe transfer, only when the clawback's payout names none.

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_execute",
    "arguments": {
      "id": "11111111-1111-4111-8111-111111111111",
      "body": {
        "originalStripeTransferId": "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 200) the tool returns one text item holding the API's JSON, pretty-printed.

The clawback's detail after the attempt, and what the execution did

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
  },
  "execution": {
    "clawbackId": "11111111-1111-4111-8111-111111111111",
    "connectBalance": 1,
    "error": "string",
    "offsets": [
      {}
    ],
    "reversalRecovered": 1,
    "stripeReversalId": "string",
    "transferReversalState": "NOT_ATTEMPTED"
  }
}

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: The clawback is not APPROVED or EXECUTING (CLAWBACK_NOT_EXECUTABLE), no Stripe transfer is known for its payout (CLAWBACK_TRANSFER_UNKNOWN), or the written notice could not be sent (CLAWBACK_NOTICE_NOT_SENT) — nothing was recovered, the clawback stays APPROVED, and the same call retries.

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_execute",
  "description": "POST /api/finance/clawbacks/{id}/execute — The retry for an approval whose notice or execution did not finish. Sends the written notice when `noticeSentAt` is null (nothing is recovered before it — 409 `CLAWBACK_NOTICE_NOT_SENT` when it still cannot be sent), then reverses the payout's Stripe transfer by what is still owed, records what the clinic's Stripe balance covered, and offsets credit the clinic holds. A reversal already booked is not repeated; a reversal Stripe refuses is recorded FAILED and answered 200 with `error`, so it can be executed again. PFF_DISCRETIONARY recovers by offset only. When the payout names no transfer (`needsTransferId`), give it as `originalStripeTransferId`.\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: { originalStripeTransferId: string (The payout's Stripe transfer, only when the clawback's payout names none.) }"
      }
    },
    "required": [
      "id"
    ]
  },
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": true,
    "idempotentHint": false,
    "openWorldHint": false
  }
}

post_finance_clawbacks_by_id_execute

Arguments

Fields of body

Example call

Result

Fields

When it fails

`post_finance_clawbacks_by_id_execute`

Fields of `body`