# Confirm a withdrawal

Confirms the exact reviewed withdrawal and atomically spends its approval while claiming the financial operation. A duplicate confirmation returns the retained outcome or unresolved resource without executing again. Authority and terms are rechecked before dispatch; a consumed approval does not imply funds moved. The durable withdrawal lookup and financial operation resource retain pending, refused, uncertain and settled outcomes. Never automatically retry an unresolved financial action.

`POST /v1/users/{userId}/wallet/withdrawals/{operationId}/confirm`

## Authentication

Both headers are required.

- Header: `X-Api-Key: YOUR_API_KEY`
- Header: `Authorization: Bearer YOUR_USER_TOKEN`

## Path parameters



```json
[
  {
    "schema": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "in": "path",
    "name": "userId",
    "required": true,
    "description": "The user in the path; must equal the token's own account."
  },
  {
    "schema": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "in": "path",
    "name": "operationId",
    "required": true,
    "description": "The withdrawal's id, from `wallets.prepareWithdrawal`."
  }
]
```


## Request body



```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "approvalId": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
            "description": "The approval id `wallets.prepareWithdrawal` returned."
          },
          "fingerprint": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200,
            "description": "The exact fingerprint `wallets.prepareWithdrawal` returned."
          }
        },
        "required": [
          "approvalId",
          "fingerprint"
        ],
        "additionalProperties": false
      }
    }
  }
}
```


## Request example

Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it.

```sh
curl --request POST 'https://api.example.test/v1/users/YOUR_USER_ID/wallet/withdrawals/YOUR_OPERATION_ID/confirm' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Authorization: Bearer YOUR_USER_TOKEN' \
  --header 'Content-Type: application/json' \
  --data-binary '@request.json'
```

## Responses

### 200

The outcome reached before answering.



```json
{
  "description": "The outcome reached before answering.",
  "content": {
    "application/json": {
      "schema": {
        "anyOf": [
          {
            "type": "object",
            "properties": {
              "status": {
                "type": "string",
                "description": "The request resolved without attempting a financial action.",
                "enum": [
                  "no_trade"
                ]
              }
            },
            "required": [
              "status"
            ]
          },
          {
            "type": "object",
            "properties": {
              "status": {
                "type": "string",
                "description": "The financial command refused execution under its authority or safety checks.",
                "enum": [
                  "refused"
                ]
              },
              "scope": {
                "type": "string",
                "enum": [
                  "authority",
                  "request",
                  "transient",
                  "insufficient_funds",
                  "request_frozen",
                  "verification",
                  "stale_evidence",
                  "account_busy",
                  "conflict",
                  "paused",
                  "held",
                  "withdrawn"
                ],
                "description": "The bounded category of the refusal; no provider text, account details or amounts are exposed here."
              }
            },
            "required": [
              "status",
              "scope"
            ]
          },
          {
            "type": "object",
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "settled",
                  "pending",
                  "partial",
                  "refunded",
                  "not_executed"
                ],
                "description": "The financial outcome: settled, unresolved, mixed or incomplete, refunded, or conclusively not executed. Partial may still await receipts; the operation's terminal field states whether reconciliation remains."
              },
              "reason": {
                "description": "Present when execution was restricted to a mode that cannot sign or move funds.",
                "type": "string",
                "enum": [
                  "signing_disabled"
                ]
              },
              "legs": {
                "maxItems": 16,
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "index": {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 15,
                      "description": "The leg's zero-based position in the frozen plan."
                    },
                    "state": {
                      "type": "string",
                      "enum": [
                        "claimed",
                        "signed",
                        "uncertain",
                        "settled",
                        "refunded",
                        "not_executed"
                      ],
                      "description": "The recorded execution or settlement state of this actual leg."
                    }
                  },
                  "required": [
                    "index",
                    "state"
                  ]
                },
                "description": "The actual execution legs represented by this outcome; unattempted planned legs have no invented receipt."
              }
            },
            "required": [
              "status",
              "legs"
            ]
          }
        ]
      }
    }
  }
}
```


### 400

The request could not be read as this operation expects.

- `invalid_input` — the body or query failed validation; `issues` names each field
- `invalid_cursor` — the `cursor` is not one this list minted



```json
{
  "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```


### 401

A credential is missing, invalid or expired.

- `partner_key_required` — no `X-Api-Key` header was sent
- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked
- `credential_expired` — the user token has expired; obtain a fresh one



```json
{
  "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```


### 403

The credentials are valid but may not do this.

- `subject_mismatch` — the `{userId}` in the path is not the token's user
- `account_disabled` — an operator disabled the account
- `origin_rejected` — a browser `Origin` other than the configured web origin



```json
{
  "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```


### 404

The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.



```json
{
  "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```


### 409

The operation lost to the current state.

- `withdrawal_changed` — the withdrawal cannot be prepared or confirmed as asked: the balance no longer covers it, its terms changed or expired, or it is already in progress



```json
{
  "description": "The operation lost to the current state.\n\n- `withdrawal_changed` — the withdrawal cannot be prepared or confirmed as asked: the balance no longer covers it, its terms changed or expired, or it is already in progress",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```


### 412

The identity is verified but has no account yet.

- `account_not_provisioned` — the identity is verified but has no account yet; call `users.ensure` first



```json
{
  "description": "The identity is verified but has no account yet.\n\n- `account_not_provisioned` — the identity is verified but has no account yet; call `users.ensure` first",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```


### 413

The body exceeds the size this deployment accepts.



```json
{
  "description": "The body exceeds the size this deployment accepts.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```


### 429

A limiter refused the request; honour `Retry-After`.

- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`



```json
{
  "description": "A limiter refused the request; honour `Retry-After`.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```


### 500

A fault on our side; quote `requestId` when reporting it.

- `internal` — a fault on our side; quote `requestId` when reporting it



```json
{
  "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```


### 503

The replica is draining or a dependency did not answer; `retryable` says whether to try again.

- `internal` — a fault on our side; quote `requestId` when reporting it



```json
{
  "description": "The replica is draining or a dependency did not answer; `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```


## Complete OpenAPI definition

The exact operation and all referenced components, including recursive schemas.



```json
{
  "operation": {
    "operationId": "wallets.confirmWithdrawal",
    "summary": "Confirm a withdrawal",
    "tags": [
      "wallets"
    ],
    "description": "Confirms the exact reviewed withdrawal and atomically spends its approval while claiming the financial operation. A duplicate confirmation returns the retained outcome or unresolved resource without executing again. Authority and terms are rechecked before dispatch; a consumed approval does not imply funds moved. The durable withdrawal lookup and financial operation resource retain pending, refused, uncertain and settled outcomes. Never automatically retry an unresolved financial action.",
    "requestBody": {
      "required": true,
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "approvalId": {
                "type": "string",
                "format": "uuid",
                "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
                "description": "The approval id `wallets.prepareWithdrawal` returned."
              },
              "fingerprint": {
                "type": "string",
                "minLength": 1,
                "maxLength": 200,
                "description": "The exact fingerprint `wallets.prepareWithdrawal` returned."
              }
            },
            "required": [
              "approvalId",
              "fingerprint"
            ],
            "additionalProperties": false
          }
        }
      }
    },
    "parameters": [
      {
        "schema": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
        },
        "in": "path",
        "name": "userId",
        "required": true,
        "description": "The user in the path; must equal the token's own account."
      },
      {
        "schema": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
        },
        "in": "path",
        "name": "operationId",
        "required": true,
        "description": "The withdrawal's id, from `wallets.prepareWithdrawal`."
      }
    ],
    "security": [
      {
        "apiKey": [],
        "userToken": []
      }
    ],
    "responses": {
      "200": {
        "description": "The outcome reached before answering.",
        "content": {
          "application/json": {
            "schema": {
              "anyOf": [
                {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "description": "The request resolved without attempting a financial action.",
                      "enum": [
                        "no_trade"
                      ]
                    }
                  },
                  "required": [
                    "status"
                  ]
                },
                {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "description": "The financial command refused execution under its authority or safety checks.",
                      "enum": [
                        "refused"
                      ]
                    },
                    "scope": {
                      "type": "string",
                      "enum": [
                        "authority",
                        "request",
                        "transient",
                        "insufficient_funds",
                        "request_frozen",
                        "verification",
                        "stale_evidence",
                        "account_busy",
                        "conflict",
                        "paused",
                        "held",
                        "withdrawn"
                      ],
                      "description": "The bounded category of the refusal; no provider text, account details or amounts are exposed here."
                    }
                  },
                  "required": [
                    "status",
                    "scope"
                  ]
                },
                {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": [
                        "settled",
                        "pending",
                        "partial",
                        "refunded",
                        "not_executed"
                      ],
                      "description": "The financial outcome: settled, unresolved, mixed or incomplete, refunded, or conclusively not executed. Partial may still await receipts; the operation's terminal field states whether reconciliation remains."
                    },
                    "reason": {
                      "description": "Present when execution was restricted to a mode that cannot sign or move funds.",
                      "type": "string",
                      "enum": [
                        "signing_disabled"
                      ]
                    },
                    "legs": {
                      "maxItems": 16,
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "index": {
                            "type": "integer",
                            "minimum": 0,
                            "maximum": 15,
                            "description": "The leg's zero-based position in the frozen plan."
                          },
                          "state": {
                            "type": "string",
                            "enum": [
                              "claimed",
                              "signed",
                              "uncertain",
                              "settled",
                              "refunded",
                              "not_executed"
                            ],
                            "description": "The recorded execution or settlement state of this actual leg."
                          }
                        },
                        "required": [
                          "index",
                          "state"
                        ]
                      },
                      "description": "The actual execution legs represented by this outcome; unattempted planned legs have no invented receipt."
                    }
                  },
                  "required": [
                    "status",
                    "legs"
                  ]
                }
              ]
            }
          }
        }
      },
      "400": {
        "$ref": "#/components/responses/InvalidInput"
      },
      "401": {
        "$ref": "#/components/responses/Unauthorized"
      },
      "403": {
        "$ref": "#/components/responses/Forbidden"
      },
      "404": {
        "$ref": "#/components/responses/NotFound"
      },
      "409": {
        "description": "The operation lost to the current state.\n\n- `withdrawal_changed` — the withdrawal cannot be prepared or confirmed as asked: the balance no longer covers it, its terms changed or expired, or it is already in progress",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "412": {
        "$ref": "#/components/responses/AccountNotProvisioned"
      },
      "413": {
        "$ref": "#/components/responses/PayloadTooLarge"
      },
      "429": {
        "$ref": "#/components/responses/TooManyRequests"
      },
      "500": {
        "$ref": "#/components/responses/Internal"
      },
      "503": {
        "$ref": "#/components/responses/Unavailable"
      }
    }
  },
  "components": {
    "responses": {
      "InvalidInput": {
        "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "Forbidden": {
        "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "NotFound": {
        "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "AccountNotProvisioned": {
        "description": "The identity is verified but has no account yet.\n\n- `account_not_provisioned` — the identity is verified but has no account yet; call `users.ensure` first",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "PayloadTooLarge": {
        "description": "The body exceeds the size this deployment accepts.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "TooManyRequests": {
        "description": "A limiter refused the request; honour `Retry-After`.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "Internal": {
        "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "Unavailable": {
        "description": "The replica is draining or a dependency did not answer; `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      }
    },
    "schemas": {
      "ProblemDetails": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "The kind of problem as a URN, `urn:fin:error:<kind>`; stable, compare against it"
          },
          "title": {
            "type": "string",
            "description": "The kind's human title, for logs; never parse it"
          },
          "status": {
            "type": "integer",
            "minimum": 400,
            "maximum": 599,
            "description": "The HTTP status, repeated in the body"
          },
          "reason": {
            "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (409) — the user's spend headroom is gone, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (409) — no execution capacity is free right now; `retryable` says whether to try again\n- `execution_unavailable` (409) — the execution engine could not take the work\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the `revision` sent is stale; reload the automation\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_completed` (409) — the automation has finished for good and cannot fire again\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (409) — the run profile names a tool this deployment does not have\n- `deployment_paused` (409) — an operator paused a deployment control; nothing was admitted or fired\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the withdrawal cannot be prepared or confirmed as asked: the balance no longer covers it, its terms changed or expired, or it is already in progress\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `account_not_provisioned` (412) — the identity is verified but has no account yet; call `users.ensure` first\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `engine_unavailable` (503) — the execution engine did not answer\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the operator credential lacks the scope this call needs\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `stream_capacity` (429) — no stream socket is free on this replica or for this user; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted",
            "type": "string",
            "enum": [
              "run_active",
              "budget_exhausted",
              "approval_not_pending",
              "execution_capacity",
              "execution_unavailable",
              "stop_pending",
              "automation_changed",
              "automation_held",
              "automation_invalid",
              "automation_completed",
              "automation_limit",
              "profile_unknown_tool",
              "deployment_paused",
              "run_not_active",
              "withdrawal_changed",
              "credential_expired",
              "account_disabled",
              "account_not_provisioned",
              "provider_unavailable",
              "engine_unavailable",
              "invalid_input",
              "internal",
              "partner_key_required",
              "partner_key_invalid",
              "subject_mismatch",
              "origin_rejected",
              "permission_required",
              "rate_limited",
              "stream_capacity",
              "invalid_cursor"
            ]
          },
          "requestId": {
            "type": "string",
            "description": "The id Fin used for this request; quote it when reporting a problem"
          },
          "retryable": {
            "type": "boolean",
            "description": "Whether repeating the same request later can succeed without changing it"
          },
          "detail": {
            "description": "Only on `invalid_input`: which part of the request failed validation",
            "type": "string"
          },
          "issues": {
            "description": "Only on `invalid_input`: one entry per failing field",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "path": {
                  "type": "string",
                  "description": "The JSON pointer of the failing field; empty for the root object"
                },
                "message": {
                  "type": "string",
                  "description": "Why the field failed"
                }
              },
              "required": [
                "path",
                "message"
              ]
            }
          }
        },
        "required": [
          "type",
          "title",
          "status",
          "requestId",
          "retryable"
        ],
        "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack."
      }
    },
    "securitySchemes": {
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Api-Key"
      },
      "userToken": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    }
  }
}
```