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

# Manually dispatch a refund for a failed or cancelled transaction

> Starts the refund workflow for the transaction's existing RefundPlan. Bypasses the `autoRefund: false` preference, so this is the way to trigger refunds for transactions that were created with auto-refund disabled. Optionally accepts a `refundDestination` override which is validated against the PFI capability and replaces the stored destination before dispatch. Only plans in `Created` or `Eligible` status can be dispatched manually.



## OpenAPI

````yaml https://sandbox-api.borderless.xyz/v1/api-json post /v1/transactions/{id}/refund
openapi: 3.0.0
info:
  title: Borderless API
  description: The Borderless API documentation.
  version: '1.0'
  contact: {}
servers:
  - url: https://sandbox-api.borderless.xyz
security: []
tags: []
paths:
  /v1/transactions/{id}/refund:
    post:
      tags:
        - Refunds
      summary: Manually dispatch a refund for a failed or cancelled transaction
      description: >-
        Starts the refund workflow for the transaction's existing RefundPlan.
        Bypasses the `autoRefund: false` preference, so this is the way to
        trigger refunds for transactions that were created with auto-refund
        disabled. Optionally accepts a `refundDestination` override which is
        validated against the PFI capability and replaces the stored destination
        before dispatch. Only plans in `Created` or `Eligible` status can be
        dispatched manually.
      operationId: RefundsController_dispatchRefund
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ManualRefundDispatchDto'
      responses:
        '202':
          description: Refund workflow dispatched. Returns the current RefundResolution.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundResolutionEntity'
      security:
        - bearer: []
components:
  schemas:
    ManualRefundDispatchDto:
      type: object
      properties:
        refundDestination:
          description: >-
            Optional override for the refund destination. When provided,
            replaces the stored `RefundPlan.destination` before the workflow is
            dispatched. The override is re-validated against the PFI's refund
            capability using the same rules as on transaction creation.
          allOf:
            - $ref: '#/components/schemas/RefundDestinationDto'
    RefundResolutionEntity:
      type: object
      properties:
        supported:
          type: boolean
        requiresManualAction:
          type: boolean
        path:
          allOf:
            - $ref: '#/components/schemas/RefundPath'
        status:
          allOf:
            - $ref: '#/components/schemas/RefundPlanStatus'
        dispatchMode:
          allOf:
            - $ref: '#/components/schemas/RefundDispatchMode'
        destinationSource:
          allOf:
            - $ref: '#/components/schemas/RefundDestinationSource'
        destination:
          type: object
          nullable: true
        reason:
          type: object
          nullable: true
        completedAt:
          format: date-time
          type: string
          nullable: true
        failedAt:
          format: date-time
          type: string
          nullable: true
      required:
        - supported
        - requiresManualAction
        - path
        - status
        - dispatchMode
        - destinationSource
    RefundDestinationDto:
      type: object
      properties:
        type:
          description: >-
            How a refund should be handled if the transaction fails. `address`
            returns funds to a specific crypto address. `source` returns funds
            to the original on-chain sender (Yellowcard maps this to
            `settlementInfo.refundToSourceAddress`). `provider_balance` leaves
            funds in the client's account at the PFI.
          example: Address
          allOf:
            - $ref: '#/components/schemas/RefundDestinationType'
        address:
          type: string
          description: >-
            Required when `type` is `address`. The crypto address that should
            receive the refund.
          example: '0x1234567890abcdef1234567890abcdef12345678'
        autoRefund:
          type: boolean
          description: >-
            Whether Borderless should automatically trigger the refund on
            failure. Defaults to `true`. Setting `false` records the plan as
            eligible but keeps it `Created` until ops dispatches manually.
          example: true
          default: true
      required:
        - type
    RefundPath:
      type: string
      enum:
        - InlineProvider
        - ProviderBalance
        - SourceReturn
        - ProviderObserved
        - ManualRequired
        - Unsupported
        - NotNeeded
    RefundPlanStatus:
      type: string
      enum:
        - Created
        - Eligible
        - InProgress
        - Succeeded
        - Failed
        - Blocked
        - ManualRequired
        - Unsupported
        - NotNeeded
        - Cancelled
    RefundDispatchMode:
      type: string
      enum:
        - None
        - PollOnly
        - WebhookOnly
        - WebhookAndPoll
        - SubmitAndPoll
        - SubmitAndWebhook
        - Manual
    RefundDestinationSource:
      type: string
      enum:
        - None
        - PerTransaction
        - OrganizationDefault
        - OriginalSender
        - ProviderLocked
        - Manual
    RefundDestinationType:
      type: string
      enum:
        - Address
        - Source
        - ProviderBalance
      description: >-
        How a refund should be handled if the transaction fails. `address`
        returns funds to a specific crypto address. `source` returns funds to
        the original on-chain sender (Yellowcard maps this to
        `settlementInfo.refundToSourceAddress`). `provider_balance` leaves funds
        in the client's account at the PFI.
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http

````