# Cancel a payout that was never sent (/docs/api/payouts/cancel-payout)

Asks for a payout to be cancelled. Only a payout nothing of which can have reached a provider is cancelled: it is processing, it was never sent (or every send is proven never to have left) and it is not waiting for a risk review. A payout that was sent, may have been sent (verification_pending), is final, waits for a risk review, or belongs to a payout batch or a remittance is refused with 409 payout_not_cancellable, reasons saying why (submitted, outcome_uncertain, already_completed, already_failed, already_returned, in_review, managed_by_batch, managed_by_remittance); nothing changes. The request is recorded at once and decided by the platform, under the payout's lock, before the payout would be sent: the answer is 202 with cancellation.status requested. Once cancelled, the payout's status is cancelled (failure_code cancelled_before_submission), its funds are available again and payout.cancelled is published; asking again, with any key, answers 200 with the cancelled payout. If the payout was sent in the meantime, cancellation.status becomes refused with not_cancelled_reason, and the payout goes on. Repeating the request with the same Idempotency-Key never cancels twice; the same key for another payout is 409 idempotency_key_reused.

The operation, from the OpenAPI contract (https://docs.caibopay.app/openapi.json):

```json

{
  "method": "POST",
  "path": "/v1/payouts/{id}/cancel",
  "description": "Asks for a payout to be cancelled. Only a payout nothing of which can have reached a provider is cancelled: it is processing, it was never sent (or every send is proven never to have left) and it is not waiting for a risk review. A payout that was sent, may have been sent (verification_pending), is final, waits for a risk review, or belongs to a payout batch or a remittance is refused with 409 payout_not_cancellable, reasons saying why (submitted, outcome_uncertain, already_completed, already_failed, already_returned, in_review, managed_by_batch, managed_by_remittance); nothing changes. The request is recorded at once and decided by the platform, under the payout's lock, before the payout would be sent: the answer is 202 with cancellation.status requested. Once cancelled, the payout's status is cancelled (failure_code cancelled_before_submission), its funds are available again and payout.cancelled is published; asking again, with any key, answers 200 with the cancelled payout. If the payout was sent in the meantime, cancellation.status becomes refused with not_cancelled_reason, and the payout goes on. Repeating the request with the same Idempotency-Key never cancels twice; the same key for another payout is 409 idempotency_key_reused.",
  "operationId": "cancelPayout",
  "parameters": [
    {
      "in": "path",
      "name": "id",
      "required": true,
      "schema": {
        "type": "string"
      }
    },
    {
      "$ref": "#/components/parameters/IdempotencyKey"
    }
  ],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Payout"
          }
        }
      },
      "description": "The payout is cancelled: by this request's decision or an earlier one."
    },
    "202": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Payout"
          }
        }
      },
      "description": "Accepted"
    },
    "400": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorResponse"
          }
        }
      },
      "description": "The request is not valid."
    },
    "401": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorResponse"
          }
        }
      },
      "description": "The API key is missing or not valid."
    },
    "403": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorResponse"
          }
        }
      },
      "description": "The API key lacks the required scope."
    },
    "404": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorResponse"
          }
        }
      },
      "description": "No such resource."
    },
    "409": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorResponse"
          }
        }
      },
      "description": "The Idempotency-Key was used with a different request, or the resource is in conflict."
    },
    "422": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorResponse"
          }
        }
      },
      "description": "The request is well formed but cannot be carried out."
    },
    "429": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorResponse"
          }
        }
      },
      "description": "Too many requests."
    },
    "500": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorResponse"
          }
        }
      },
      "description": "An error on our side. Safe to retry with the same Idempotency-Key."
    },
    "503": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorResponse"
          }
        }
      },
      "description": "Temporarily unavailable or suspended. Safe to retry with the same Idempotency-Key."
    }
  },
  "summary": "Cancel a payout that was never sent",
  "tags": [
    "Payouts"
  ],
  "x-required-scope": "write",
  "x-codeSamples": [
    {
      "lang": "js",
      "label": "Node.js",
      "source": "import { Caibo } from \"caibopay\";\n\nconst caibo = new Caibo(process.env.CAIBO_API_KEY);\n\nconst result = await caibo.payouts.cancel(\"pout_...\", { idempotencyKey: \"your-operation-id\" });"
    },
    {
      "lang": "python",
      "label": "Python",
      "source": "import os\n\nimport caibopay\n\nclient = caibopay.Client(os.environ[\"CAIBO_API_KEY\"])\n\nresult = client.payouts.cancel(\"pout_...\", idempotency_key=\"your-operation-id\")"
    },
    {
      "lang": "go",
      "label": "Go",
      "source": "client, err := caibopay.NewClient(os.Getenv(\"CAIBO_API_KEY\"))\nif err != nil {\n\treturn err\n}\nctx := context.Background()\n\nresult, err := client.Payouts.Cancel(ctx, \"pout_...\", caibopay.WithIdempotencyKey(\"your-operation-id\"))\nif err != nil {\n\treturn err\n}\nfmt.Println(result)"
    }
  ]
}

```