> ## Documentation Index > Fetch the complete documentation index at: https://docs.tracefinance.com/llms.txt > Use this file to discover all available pages before exploring further. # Refund a deposit > Refunds a completed deposit in full, returning the funds to the original payer. ## OpenAPI ````yaml apis/fx-payment/openapi.yml POST /v1/operations/{operationId}/refund openapi: 3.1.1 info: title: Trace Finance Payments API version: 1.0.0 description: > API for deposits, withdrawals, swaps, and beneficiary management on the Trace Finance platform. servers: - url: https://api.sandbox.tracefinance.com description: Sandbox security: - bearerAuth: [] tags: - name: Operations description: >- Create deposits, withdrawals, and swaps. Query operation status and history. - name: Reports description: Generate aggregated views of operations across a time window. - name: Beneficiaries description: >- Manage external beneficiaries and their payment instructions for withdrawals. - name: Payment instructions description: Add or remove payment instructions on an existing beneficiary. paths: /v1/operations/{operationId}/refund: post: tags: - Operations summary: Refund a deposit description: > Refunds a completed deposit in full, returning the funds to the original payer. Only a `DEPOSIT` operation in `COMPLETED` status can be refunded, and the refund is always for the full amount — there is no partial refund. The refund is tracked on the existing deposit operation; no new operation is created. Returns `202` with no response body — the refund settles asynchronously. The deposit stays `COMPLETED` while the return is in flight and reaches `REFUNDED` once the outbound payment settles; the outbound leg is added to `transactions` once confirmed. If the return fails, the deposit stays `COMPLETED`. The `motive` is recorded as the `reason` on the `REFUNDED` state. Follow the outcome with `GET /v1/operations/{operationId}`. operationId: refundDeposit parameters: - $ref: '#/components/parameters/OperationId' - $ref: '#/components/parameters/IdempotencyKey' - $ref: '#/components/parameters/TraceVersion' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RefundDepositRequest' examples: customerRequest: summary: Refund a deposit at the customer's request value: motive: code: CUSTOMER_REQUEST message: Customer requested the deposit be returned fraud: summary: Refund a deposit flagged as fraud value: motive: code: FRAUD message: Deposit linked to a fraudulent transaction responses: '202': description: > Refund accepted for processing. No response body. Poll `GET /v1/operations/{operationId}` to follow the deposit to `REFUNDED`. headers: X-Request-Id: $ref: '#/components/headers/RequestId' '400': description: 'Validation error: missing or malformed fields.' headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingMotive: summary: motive is missing value: code: INVALID_DATA message: Object contains invalid data details: errors: - code: REQUIRED message: Parameter 'body:motive' not found in request field: body:motive params: {} invalidMotiveCode: summary: motive.code is not one of the accepted values value: code: INVALID_DATA message: Object contains invalid data details: errors: - code: INVALID_ENUM message: '''CHARGEBACK'' is not a valid motive code' field: body:motive.code params: {} '401': $ref: '#/components/responses/UnauthorizedError' '404': description: Operation not found for this customer. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: operationNotFound: $ref: '#/components/examples/OperationNotFound' '409': description: Idempotency key was reused with a different request body. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: idempotencyConflict: $ref: '#/components/examples/IdempotencyConflict' '422': description: Business rule violation — the operation cannot be refunded. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: notRefundable: summary: >- Operation type cannot be refunded (only deposits are refundable) value: code: OPERATION_NOT_REFUNDABLE message: Only deposit operations can be refunded details: operationId: 1f3a8c8d-2e1a-4b3a-9d2e-7c1a4b3a9d2e intentType: WITHDRAWAL notCompleted: summary: Deposit has not completed and cannot be refunded value: code: OPERATION_NOT_REFUNDABLE message: Deposit must be in COMPLETED status to be refunded details: operationId: 3b5c0e0f-4a3c-6d5c-bf4a-9e3c6d5cbf4a status: REQUESTED alreadyRefunded: summary: Deposit was already refunded value: code: OPERATION_NOT_REFUNDABLE message: Deposit has already been refunded details: operationId: 3b5c0e0f-4a3c-6d5c-bf4a-9e3c6d5cbf4a status: REFUNDED components: parameters: OperationId: name: operationId in: path required: true description: UUID of the operation. schema: type: string format: uuid IdempotencyKey: name: X-Idempotency-Key in: header required: true description: >- Unique key to ensure idempotent request processing. Required on all `POST`, `PUT`, and `PATCH` requests. schema: type: string format: uuid TraceVersion: name: X-Trace-Version in: header required: false description: API version. Omit to use the default version. schema: type: string example: '1' schemas: RefundDepositRequest: type: object description: > Request to refund a completed deposit. The refund is always for the full deposit amount and returns the funds to the original payer. properties: motive: $ref: '#/components/schemas/RefundMotive' required: - motive ErrorResponse: type: object properties: code: type: string description: Machine-readable error code. message: type: string description: Human-readable description. details: type: object additionalProperties: true required: - code - message RefundMotive: type: object description: > Why the deposit is being refunded. Recorded as the `reason` on the operation's `REFUNDED` state. properties: code: type: string description: Machine-readable refund reason. enum: - CUSTOMER_REQUEST - FRAUD example: CUSTOMER_REQUEST message: type: string description: Human-readable explanation for the refund. example: Customer requested the deposit be returned required: - code - message headers: RequestId: description: >- Unique request identifier emitted on every response. Reference it when contacting Trace Finance support so we can trace the request end-to-end. See [Errors](/guides/principles/errors). schema: type: string format: uuid responses: UnauthorizedError: description: Missing or invalid authentication token. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalidToken: $ref: '#/components/examples/InvalidToken' expiredToken: $ref: '#/components/examples/ExpiredToken' examples: OperationNotFound: summary: Operation does not exist for the authenticated customer value: code: RESOURCE_NOT_FOUND message: >- Operation with given parameters [id:1f3a8c8d-2e1a-4b3a-9d2e-7c1a4b3a9d2e] not found details: resource: Operation parameters: id: 1f3a8c8d-2e1a-4b3a-9d2e-7c1a4b3a9d2e IdempotencyConflict: summary: X-Idempotency-Key was reused with a different request body value: code: IDEMPOTENCY_CONFLICT message: Idempotency key already used with a different request details: {} InvalidToken: summary: Bearer token is invalid or malformed value: code: INVALID_ACCESS_TOKEN message: Invalid access token details: {} ExpiredToken: summary: Bearer token has expired value: code: EXPIRED_ACCESS_TOKEN message: Expired access token details: {} securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- JWT bearer token. Include as `Authorization: Bearer `. See the [Authentication](/guides/authentication) guide for how to obtain one. ````