---
updatedAt: 2026-04-30T03:13:44.000Z
agentTools:
  projectIndex: https://developers.akahu.nz/llms.txt
---

# Cancel pending one-off payment

Note that cancellation is only possible before the payment is authorised (while it's status is `READY`).

Upon cancellation payments will not be processed and the user will be 
directed back to the 'redirect_uri'.

# OpenAPI definition

```json
{
  "info": {
    "title": "Akahu One-Off Payments API",
    "version": "1.0.0"
  },
  "servers": [
    {
      "description": "Akahu One-off Payments API",
      "url": "https://api.payments.akahu.io"
    }
  ],
  "x-readme": {
    "apply-endpoint-order": true
  },
  "openapi": "3.1.0",
  "components": {
    "schemas": {
      "OneOffPaymentId": {
        "type": "string",
        "pattern": "^one_off_payment_[a-z0-9]{25,27}$",
        "example": "one_off_payment_c01234567890123456789012345"
      },
      "Generic400ErrorResponseCode": {
        "type": "string",
        "enum": [
          "invalid",
          "invalid_id",
          "not_found",
          "bad_request",
          "invalid_type",
          "invalid_literal",
          "invalid_union",
          "invalid_union_discriminator",
          "invalid_enum_value",
          "unrecognized_keys",
          "invalid_arguments",
          "invalid_return_type",
          "invalid_date",
          "invalid_string",
          "too_small",
          "too_big",
          "invalid_intersection_types",
          "not_multiple_of",
          "not_finite"
        ]
      },
      "IssuePath": {
        "type": "array",
        "items": {
          "title": "IssuePathSegment",
          "oneOf": [
            {
              "type": "string"
            },
            {
              "type": "number"
            }
          ]
        }
      },
      "Generic401ErrorResponseCode": {
        "type": "string",
        "enum": [
          "unauthorized"
        ]
      },
      "Generic401ErrorResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "message": {
            "type": "string"
          },
          "issues": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "code": {
                  "$ref": "#/components/schemas/Generic401ErrorResponseCode"
                },
                "message": {
                  "type": "string"
                },
                "path": {
                  "$ref": "#/components/schemas/IssuePath"
                }
              },
              "required": [
                "code",
                "message",
                "path"
              ]
            }
          }
        },
        "required": [
          "success",
          "message",
          "issues"
        ]
      },
      "Generic403ErrorResponseCode": {
        "type": "string",
        "enum": [
          "forbidden"
        ]
      },
      "Generic403ErrorResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "message": {
            "type": "string"
          },
          "issues": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "code": {
                  "$ref": "#/components/schemas/Generic403ErrorResponseCode"
                },
                "message": {
                  "type": "string"
                },
                "path": {
                  "$ref": "#/components/schemas/IssuePath"
                }
              },
              "required": [
                "code",
                "message",
                "path"
              ]
            }
          }
        },
        "required": [
          "success",
          "message",
          "issues"
        ]
      },
      "Generic404ErrorResponseCode": {
        "type": "string",
        "enum": [
          "not_found"
        ]
      },
      "Generic404ErrorResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "message": {
            "type": "string"
          },
          "issues": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "code": {
                  "$ref": "#/components/schemas/Generic404ErrorResponseCode"
                },
                "message": {
                  "type": "string"
                },
                "path": {
                  "$ref": "#/components/schemas/IssuePath"
                }
              },
              "required": [
                "code",
                "message",
                "path"
              ]
            }
          }
        },
        "required": [
          "success",
          "message",
          "issues"
        ]
      },
      "CancelOneOffPayment400ErrorResponseCode": {
        "type": "string",
        "enum": [
          "bad_payment_state"
        ]
      },
      "CancelOneOffPayment400ErrorResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "message": {
            "type": "string"
          },
          "issues": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "code": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/Generic400ErrorResponseCode"
                    },
                    {
                      "$ref": "#/components/schemas/CancelOneOffPayment400ErrorResponseCode"
                    }
                  ]
                },
                "message": {
                  "type": "string"
                },
                "path": {
                  "$ref": "#/components/schemas/IssuePath"
                }
              },
              "required": [
                "code",
                "message",
                "path"
              ]
            }
          }
        },
        "required": [
          "success",
          "message",
          "issues"
        ]
      }
    }
  },
  "paths": {
    "/v1/one-off-payments/{paymentId}/cancel": {
      "put": {
        "operationId": "CancelOneOffPayment",
        "tags": [
          "Payments"
        ],
        "summary": "Cancel pending one-off payment",
        "description": "Note that cancellation is only possible before the payment is authorised (while it's status is `READY`).\n\nUpon cancellation payments will not be processed and the user will be \ndirected back to the 'redirect_uri'.",
        "deprecated": false,
        "security": [
          {
            "AppSecret": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "$ref": "#/components/schemas/OneOffPaymentId"
            },
            "required": true,
            "name": "paymentId",
            "in": "path"
          }
        ],
        "responses": {
          "204": {
            "description": "Accepted"
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CancelOneOffPayment400ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Generic401ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Generic403ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Payment not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Generic404ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  }
}
```