> ## Documentation Index > Fetch the complete documentation index at: https://docs.hyperprop.com/llms.txt > Use this file to discover all available pages before exploring further. # Reverse a payout (restore the withdrawn balance) > Reverse a payout that was cancelled **after** the funds were withdrawn: the payout amount is credited back to the account and the payout is marked `reversed` in the ledger. One call — no manual balance edits. **What a reversal does to the account (mirror of the payout):** 1. Adds the payout `amount` back to the balance. The high-water mark and the daily baseline move **up by the same amount**, so the credit never appears as trading profit, Day P&L, or reduced drawdown room. 2. Decrements `payoutCount` by one (`maxPayouts` counts only non-reversed payouts from now on). 3. Payout cycle: when the payout started the current consistency cycle (`consistencyReset`) or a later payout did, the cycle starting balance moves up by the amount too, so the credit does not count as cycle profit. When the payout happened inside the current cycle, the restored balance restores that cycle's profit exactly. 4. A loss floor locked by the payout (`moveMllToLock`) is **left unchanged** and returned as `lossFloorBalance`; adjust it yourself if the cancellation should unlock it. **Rules:** - The account must be flat (no open positions or working orders) and tradable (`not_started`/`in_progress`). Passed, failed, expired and turned-off (`inactive`) accounts are refused. - Any payout of the account can be reversed, not only the latest; the cycle handling above applies to each. - A payout can be reversed **once** — a second attempt returns 409 `PAYOUT_ALREADY_REVERSED`. The credit is applied atomically with the ledger update, so it can never be applied twice. - Reversed payouts stay in `GET /accounts/{accountId}/payouts` with `status: "reversed"` and are excluded from payout activity totals. **Idempotency (recommended):** send an `Idempotency-Key` (or `x-idempotency-key`) header. A replay with the same key returns the original reversal (200, `duplicate: true`) and never credits twice. After a 502 `REVERSAL_NOT_CONFIRMED`, retry with the **same** key: the retry either confirms the earlier reversal or completes it. 4xx answers are cached per key, so after fixing the cause (e.g. flattening the account) retry with a new key. **Webhooks:** `account.payout_reversed` (with a `payout` block: amount, balances before/after the reversal, new payout count, original payout details). Subscribers of `account.balance_changed` also receive the balance credit. **Example:** ```bash curl -X POST ".../v1/organization/accounts/7c9e6679-7425-40de-944b-e07fc1f90ae7/payouts/e5f6a7b8-c9d0-1234-ef01-234567890abc/reverse" \ -H "X-API-Key: hp_liv...ere" \ -H "Idempotency-Key: reverse-PO-1042" \ -H "Content-Type: application/json" \ -d '{ "reason": "Payout PO-1042 cancelled by finance" }' ``` **Error codes:** | Code | Meaning | |------|---------| | `ACCOUNT_NOT_FOUND` / `PAYOUT_NOT_FOUND` | Not in your organization / not a payout of this account (404) | | `PAYOUT_ALREADY_REVERSED` | The payout was already reversed (409) | | `OPEN_EXPOSURE` | Account has open positions/working orders — flatten first (409) | | `ACCOUNT_NOT_TRADABLE` | Account is passed/failed/expired/turned off (409) | | `PAYOUT_REVERSAL_IN_PROGRESS` | Another request is reversing this payout right now (409) | | `ENGINE_UNAVAILABLE` | The reversal could not be applied — NOT reversed; retry (502) | | `REVERSAL_NOT_CONFIRMED` | The outcome could not be confirmed — retry with the same idempotency key; never applied twice (502) | **Permissions:** requires **manage** access to "Payouts". **Authentication:** send your organization API key in the `X-API-Key` header. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/organization/accounts/{accountId}/payouts/{payoutId}/reverse openapi: 3.0.0 info: title: Hyperprop Platform API version: 1.0.0 description: >- REST API for the Hyperprop Trading Platform — provision evaluation and funded trading accounts, manage traders and plans, react to account lifecycle events via signed webhooks, and reconcile billing. Built for prop firms integrating from their own backend. Authentication, quick start, error handling, idempotency, pagination, custom metadata, webhooks, and the MCP connector are documented at https://docs.hyperprop.com. x-logo: url: https://app.hyperprop.com/logo-icon.svg altText: Hyperprop href: https://hyperprop.com servers: - url: https://api.hyperprop.com/platform description: Production security: [] tags: - name: Trading accounts description: Create, update, and inspect trading accounts. - name: Traders description: Look up and update the traders in your organization. - name: Trading plans description: Define the plans you sell. - name: Trading rules description: Define how accounts are evaluated. - name: Lockouts description: Pause and resume trading on an account. - name: Payouts description: Check payout eligibility and record payouts. - name: Purchases description: Purchases recorded for your organization. - name: Time Machine description: Restore accounts to an earlier trading day or instant. - name: Webhooks description: Register webhook endpoints and inspect deliveries. - name: Events description: Your organization's event history and real-time event stream. - name: Reconciliation description: Balances, end-of-day snapshots, and fills for reconciliation. - name: Analytics description: Organization performance and plan economics. - name: Billing description: 'Your Hyperprop bill: activity, billing cycles, and forecasts.' - name: Team and roles description: Manage dashboard access for your staff. - name: API keys description: Manage your organization's API key. - name: Logs and health description: API request logs, the audit log, and integration health. - name: Organization profile description: Your organization's profile and logo. - name: Support description: Open and follow up on support tickets. - name: Partner access description: >- Read a trader's journal as an approved partner app, with the trader's own key. paths: /v1/organization/accounts/{accountId}/payouts/{payoutId}/reverse: post: tags: - Payouts summary: Reverse a payout (restore the withdrawn balance) description: >- Reverse a payout that was cancelled **after** the funds were withdrawn: the payout amount is credited back to the account and the payout is marked `reversed` in the ledger. One call — no manual balance edits. **What a reversal does to the account (mirror of the payout):** 1. Adds the payout `amount` back to the balance. The high-water mark and the daily baseline move **up by the same amount**, so the credit never appears as trading profit, Day P&L, or reduced drawdown room. 2. Decrements `payoutCount` by one (`maxPayouts` counts only non-reversed payouts from now on). 3. Payout cycle: when the payout started the current consistency cycle (`consistencyReset`) or a later payout did, the cycle starting balance moves up by the amount too, so the credit does not count as cycle profit. When the payout happened inside the current cycle, the restored balance restores that cycle's profit exactly. 4. A loss floor locked by the payout (`moveMllToLock`) is **left unchanged** and returned as `lossFloorBalance`; adjust it yourself if the cancellation should unlock it. **Rules:** - The account must be flat (no open positions or working orders) and tradable (`not_started`/`in_progress`). Passed, failed, expired and turned-off (`inactive`) accounts are refused. - Any payout of the account can be reversed, not only the latest; the cycle handling above applies to each. - A payout can be reversed **once** — a second attempt returns 409 `PAYOUT_ALREADY_REVERSED`. The credit is applied atomically with the ledger update, so it can never be applied twice. - Reversed payouts stay in `GET /accounts/{accountId}/payouts` with `status: "reversed"` and are excluded from payout activity totals. **Idempotency (recommended):** send an `Idempotency-Key` (or `x-idempotency-key`) header. A replay with the same key returns the original reversal (200, `duplicate: true`) and never credits twice. After a 502 `REVERSAL_NOT_CONFIRMED`, retry with the **same** key: the retry either confirms the earlier reversal or completes it. 4xx answers are cached per key, so after fixing the cause (e.g. flattening the account) retry with a new key. **Webhooks:** `account.payout_reversed` (with a `payout` block: amount, balances before/after the reversal, new payout count, original payout details). Subscribers of `account.balance_changed` also receive the balance credit. **Example:** ```bash curl -X POST ".../v1/organization/accounts/7c9e6679-7425-40de-944b-e07fc1f90ae7/payouts/e5f6a7b8-c9d0-1234-ef01-234567890abc/reverse" \ -H "X-API-Key: hp_liv...ere" \ -H "Idempotency-Key: reverse-PO-1042" \ -H "Content-Type: application/json" \ -d '{ "reason": "Payout PO-1042 cancelled by finance" }' ``` **Error codes:** | Code | Meaning | |------|---------| | `ACCOUNT_NOT_FOUND` / `PAYOUT_NOT_FOUND` | Not in your organization / not a payout of this account (404) | | `PAYOUT_ALREADY_REVERSED` | The payout was already reversed (409) | | `OPEN_EXPOSURE` | Account has open positions/working orders — flatten first (409) | | `ACCOUNT_NOT_TRADABLE` | Account is passed/failed/expired/turned off (409) | | `PAYOUT_REVERSAL_IN_PROGRESS` | Another request is reversing this payout right now (409) | | `ENGINE_UNAVAILABLE` | The reversal could not be applied — NOT reversed; retry (502) | | `REVERSAL_NOT_CONFIRMED` | The outcome could not be confirmed — retry with the same idempotency key; never applied twice (502) | **Permissions:** requires **manage** access to "Payouts". **Authentication:** send your organization API key in the `X-API-Key` header. operationId: postV1OrganizationAccountsAccountidPayoutsPayoutidReverse parameters: - description: Trading account the payout was withdrawn from x-format: guid: true name: accountId in: path required: true schema: type: string - description: Payout to reverse (id from POST/GET /accounts/{accountId}/payouts) x-format: guid: true name: payoutId in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/Model869' responses: '200': description: Payout reversed content: '*/*': schema: $ref: '#/components/schemas/Model871' '401': description: Authentication required content: '*/*': schema: $ref: '#/components/schemas/Model9' '403': description: Access denied content: '*/*': schema: $ref: '#/components/schemas/Model48' '404': description: Account or payout not found content: '*/*': schema: $ref: '#/components/schemas/Model872' '409': description: >- Already reversed, reversal in progress, open exposure, or not tradable content: '*/*': schema: $ref: '#/components/schemas/Model873' '500': description: An unexpected error occurred content: '*/*': schema: $ref: '#/components/schemas/Model5' '502': description: >- Reversal not applied (ENGINE_UNAVAILABLE) or not confirmed (REVERSAL_NOT_CONFIRMED — retry with the same idempotency key) content: '*/*': schema: $ref: '#/components/schemas/Model874' security: - X-API-Key: [] components: schemas: Model869: type: object properties: reason: type: string description: >- Why the payout is being reversed — stored on the payout, in the audit trail, and in the webhook event. example: Payout PO-1042 cancelled by finance — funds returned to account minLength: 3 maxLength: 500 x-convert: trim: true required: - reason Model871: type: object properties: success: type: boolean example: true message: type: string example: Payout reversed — balance restored data: $ref: '#/components/schemas/Model870' Model9: type: object properties: success: type: boolean description: Always false on errors example: false statusCode: type: number example: 401 error: type: string example: Unauthorized message: type: string example: Authentication required code: type: string description: Machine-readable error code — switch on this, not on message text example: UNAUTHORIZED Model48: type: object properties: success: type: boolean description: Always false on errors example: false statusCode: type: number example: 403 error: type: string example: Forbidden message: type: string example: Access denied code: type: string description: Machine-readable error code — switch on this, not on message text example: FORBIDDEN Model872: type: object properties: statusCode: type: number example: 404 error: type: string example: Not Found message: type: string example: Payout not found on this account code: type: string example: PAYOUT_NOT_FOUND Model873: type: object properties: success: type: boolean example: false code: type: string example: PAYOUT_ALREADY_REVERSED message: type: string example: This payout has already been reversed Model5: type: object properties: success: type: boolean description: Always false on errors example: false statusCode: type: number example: 500 error: type: string example: Internal Server Error message: type: string example: An unexpected error occurred code: type: string description: Machine-readable error code — switch on this, not on message text example: INTERNAL_ERROR Model874: type: object properties: success: type: boolean example: false code: type: string example: REVERSAL_NOT_CONFIRMED message: type: string example: >- The reversal could not be confirmed. Retry with the same Idempotency-Key — it is never applied twice. Model870: type: object example: payoutId: e5f6a7b8-c9d0-1234-ef01-234567890abc accountId: 7c9e6679-7425-40de-944b-e07fc1f90ae7 amount: 1600 status: reversed balanceBefore: 50900 balanceAfter: 52500 payoutCount: 0 cycleStartingBalanceShifted: true lossFloorBalance: 50100 reason: Payout PO-1042 cancelled by finance reversedAt: '2026-10-09T14:05:00.000Z' duplicate: false properties: payoutId: type: string accountId: type: string amount: type: number status: type: string balanceBefore: type: number balanceAfter: type: number payoutCount: type: number cycleStartingBalanceShifted: type: boolean lossFloorBalance: type: number reason: type: string reversedAt: type: string duplicate: type: boolean securitySchemes: X-API-Key: type: apiKey name: X-API-Key in: header description: >- Organization API key. Format: "hp_live_{key}". Organization admins manage the key in the dashboard. ```` ## Related topics - [Webhooks](/guides/webhooks.md) - [List payouts for an account](/platform-api/payouts/list-payouts-for-an-account.md) - [Execute a payout (balance withdrawal)](/platform-api/payouts/execute-a-payout-balance-withdrawal.md) - [Introduction](/introduction.md) - [Payout queue — bulk payout eligibility](/platform-api/payouts/payout-queue-—-bulk-payout-eligibility.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.