> ## Documentation Index
> Fetch the complete documentation index at: https://docs.capa.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# Cancel Transaction

Cancels a previously created on-ramp, off-ramp, or cross-ramp transaction. Cancellation is only allowed if the transaction has not yet received funds.

***

## Important Notes

* Only transactions in a **cancellable state** can be cancelled (e.g., `PENDING`, `BANK_TRANSFER_PENDING`, `CRYPTO_NOT_RECEIVED`).
* Completed or locked transactions **cannot** be cancelled.
* The transaction must belong to the authenticated partner account.
* This operation is **idempotent** — calling it multiple times on a cancelled transaction will not cause errors.

***

## Use Cases

* **Abort abandoned payments**: Cancel stuck or forgotten transaction flows.
* **Back-office controls**: Let support teams reverse pending transactions before execution.
* **Automatic timeout flows**: Cancel after inactivity via cron jobs or watchdog logic.

***

## Error Codes

### Common Errors

| HTTP Status | Code                   | Message                            |
| ----------- | ---------------------- | ---------------------------------- |
| 401         | `UNAUTHORIZED`         | "API Key is missing"               |
| 401         | `UNAUTHORIZED`         | "Invalid API Key format"           |
| 401         | `UNAUTHORIZED`         | "Invalid API Key"                  |
| 403         | `INVALID_PARTNER_FLOW` | "The partner has an invalid flow." |

### Endpoint-Specific Errors

| HTTP Status | Code                                     | Message                                        |
| ----------- | ---------------------------------------- | ---------------------------------------------- |
| 400         | `INVALID_USER_INPUT_ERROR`               | "Invalid User Input"                           |
| 400         | `BAD_REQUEST`                            | "Invalid transaction state transition"         |
| 403         | `PARTNER_NOT_OWNER_OF_TRANSACTION_ERROR` | "Partner is not the owner of the transaction." |
| 403         | `USER_NOT_OWNER_OF_TRANSACTION_ERROR`    | "User is not the owner of the transaction."    |


## OpenAPI

````yaml reference/openapi/TransactionPartnerV2Controller_cancelPartnerTransaction.json PUT /api/partner/v2/transactions/{id}/cancel
openapi: 3.0.0
info:
  title: Capa Partner API - V2
  description: >-
    Partner API for integrating cryptocurrency on-ramp and off-ramp services
    using Capa's infrastructure. Enable your users to seamlessly convert between
    fiat and crypto.
  version: v2
  contact: {}
servers:
  - url: https://staging-api.capa.fi
  - url: https://production-api.capa.fi
security: []
paths:
  /api/partner/v2/transactions/{id}/cancel:
    put:
      tags:
        - transactions
      operationId: TransactionPartnerV2Controller_cancelPartnerTransaction
      parameters:
        - name: id
          required: true
          in: path
          description: Transaction identifier
          schema:
            example: 8374f327-38bd-4b0b-b8a7-2524599eb903
            type: string
      responses:
        '200':
          description: >-
            Transaction cancelled successfully. Returns the updated transaction
            details.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        description: The identifier for the transaction.
                      userId:
                        type: string
                        description: User identifier making the transaction.
                      status:
                        type: string
                        description: Transaction status.
                    required:
                      - id
                      - userId
                      - status
                    x-readme-ref-name: CancelTransactionHttpResponse
              example:
                success: true
                data:
                  id: string
                  userId: string
                  status: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                UNAUTHORIZED:
                  value:
                    success: false
                    code: UNAUTHORIZED
                    message: API Key is missing
                UNAUTHORIZED_2:
                  value:
                    success: false
                    code: UNAUTHORIZED
                    message: Invalid API Key format
                UNAUTHORIZED_3:
                  value:
                    success: false
                    code: UNAUTHORIZED
                    message: Invalid API Key
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                code: PARTNER_NOT_OWNER_OF_TRANSACTION_ERROR
                message: Partner is not the owner of the transaction.
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                code: NOT_FOUND_ERROR
                message: Requested Transaction was not found
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                code: INVALID_TRANSACTION_STATE_TRANSITION
                message: >-
                  Cannot update status from COMPLETED to CANCELLED for
                  ON_RAMP-REGULAR
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                code: INTERNAL_SERVER_ERROR
                message: Internal server error
      security:
        - PartnerApiKey: []
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        code:
          type: string
          description: Machine-readable error code.
        message:
          type: string
          description: Human-readable error message.
        errors:
          type: array
          description: Optional per-field validation details.
          items:
            type: object
            properties:
              field:
                type: string
              message:
                type: string
      required:
        - success
        - code
        - message
  securitySchemes:
    PartnerApiKey:
      type: apiKey
      in: header
      name: partner-api-key
      description: API key for the affiliated partner performing the request.

````