`post_finance_clawbacks_by_id_offsets_by_payouttransactionid_release`

Changes data · you confirm first

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

Return an offset whose Stripe transfer failed to the clinic's balance (platform staff)

An offset run takes held credit off the clinic's balance and counts it in flight on the clawback (offsetPendingAmount) until its transfer is confirmed. When that transfer FAILED, the payout reconcile (POST /api/finance/payouts/reconcile) reports the offset PAYOUT — its row names offsetForClawbackId — and promotes it to SENT, recording its OFFSET leg, if Stripe shows the transfer moved after all. When it did not, this returns the amount to the clinic's ORG_BALANCE, stops counting it in flight and closes the PAYOUT NOT_REQUIRED. Stripe is asked first: a live transfer in the payout's transfer_group is refused (409 CLAWBACK_OFFSET_TRANSFERRED). A second release of the same offset writes nothing (release.changed false).

Arguments

Argument	Type		Description
`id`path	string (uuid)	required
`payoutTransactionId`path	string (uuid)	required	The offset PAYOUT transaction.

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_offsets_by_payouttransactionid_release",
    "arguments": {
      "id": "11111111-1111-4111-8111-111111111111",
      "payoutTransactionId": "11111111-1111-4111-8111-111111111111"
    }
  }
}

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 release, and the clawback's detail after it

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
  },
  "release": {
    "amount": 1,
    "changed": true,
    "orgBalance": 1,
    "payoutTransactionId": "11111111-1111-4111-8111-111111111111"
  }
}

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.

403: Authenticated, but the caller holds none of the required permissions.
404: No such clawback, or no offset payout with this id. Carries the DAL's sentence.
409: Stripe holds a live transfer for the offset (CLAWBACK_OFFSET_TRANSFERRED — run the reconcile), or the DAL refused: the payout is not this clawback's offset, its transfer is not FAILED, its OFFSET leg is recorded, or the clawback does not count it in flight.

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_offsets_by_payouttransactionid_release",
  "description": "POST /api/finance/clawbacks/{id}/offsets/{payoutTransactionId}/release — An offset run takes held credit off the clinic's balance and counts it in flight on the clawback (`offsetPendingAmount`) until its transfer is confirmed. When that transfer FAILED, the payout reconcile (POST /api/finance/payouts/reconcile) reports the offset PAYOUT — its row names `offsetForClawbackId` — and promotes it to SENT, recording its OFFSET leg, if Stripe shows the transfer moved after all. When it did not, this returns the amount to the clinic's ORG_BALANCE, stops counting it in flight and closes the PAYOUT NOT_REQUIRED. Stripe is asked first: a live transfer in the payout's `transfer_group` is refused (409 `CLAWBACK_OFFSET_TRANSFERRED`). A second release of the same offset writes nothing (`release.changed` false).\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"
      },
      "payoutTransactionId": {
        "type": "string",
        "description": "The offset PAYOUT transaction."
      }
    },
    "required": [
      "id",
      "payoutTransactionId"
    ]
  },
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": true,
    "idempotentHint": false,
    "openWorldHint": false
  }
}