> **Description:** Cancel payments and release reserved funds back to customer accounts.

# Cancel a payment

Cancelling a payment releases the reserved funds back to the customer's bank account.
This keeps the customer's bank statement and the payment overview in the Vipps  or MobilePay  app in sync with their expectations -- and ensures a better customer experience.

You should always **release any funds you don't plan to capture** as soon as possible.
If you are only capturing part of an authorized amount, cancel the remainder right away, so the customer can use those funds for other purposes.

A payment can be cancelled via this API or on the [business portal](https://portal.vippsmobilepay.com).

You can cancel at any time while there are remaining authorized funds. Cancelling will release these funds back to the customer.

**Payment deadlines**

All payments must be handled within the [payment capture deadlines](https://developer.vippsmobilepay.com/docs/knowledge-base/reserve-and-capture.md#capture-deadlines).
Attempting to cancel a payment after its deadline will return `HTTP 400 Bad Request`.

## Authorization

All ePayment API requests must include a valid Bearer token in the `Authorization` header.
See [Authorization](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/concepts.md#authorization) for how to obtain one.

## Creating a cancel request

To cancel an authorized payment, use
[`POST:/epayment/v1/payments/{reference}/cancel`][cancel-payment-endpoint].

For example, this request cancels the entire payment.
*Note: Once cancelled, the payment cannot be captured.*

```bash
curl -X POST https://apitest.vipps.no/epayment/v1/payments/UNIQUE-PAYMENT-REFERENCE/cancel \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
-H "Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY" \
-H "Merchant-Serial-Number: YOUR-MSN" \
-H "Vipps-System-Name: acme" \
-H "Vipps-System-Version: 3.1.2" \
-H "Vipps-System-Plugin-Name: acme-webshop" \
-H "Vipps-System-Plugin-Version: 4.5.6" \
```

The response will summarize the payment's status.
In this example, 499 NOK was authorized but not captured, and the full amount was cancelled:

```json
{
   "amount":{
      "currency":"NOK",
      "value":49900
   },
   "state":"AUTHORIZED",
   "aggregate":{
      "authorizedAmount":{
         "currency":"NOK",
         "value":49900
      },
      "cancelledAmount":{
         "currency":"NOK",
         "value":49900
      },
      "capturedAmount":{
         "currency":"NOK",
         "value":0
      },
      "refundedAmount":{
         "currency":"NOK",
         "value":0
      }
   },
   "pspReference":"37c34d8c-2649-448e-864b-060d5d93e4c4",
   "reference":"acme-shop-123-order123abc"
}
```

**Payment state**

The payment state remains `AUTHORIZED` after a cancel.
If you cancel before the customer authorizes (for example, if they change their mind), the payment state becomes `TERMINATED`.

**Webhooks**
You can receive automatic notifications when a payment is cancelled.
Register for these webhook events:

- `epayments.payment.cancelled.v1`
- `epayments.payment.terminated.v1`

For full details, see [webhooks](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/webhooks.md).

### Cancel transaction only (advanced)

It's not possible to cancel a payment when a user is actively authorizing (e.g., during a payment scheme process or 3-D Secure session).
If a cancellation request arrives too late, the user may have already authorized the payment.

To only cancel payments that have not yet been authorized, set the `cancelTransactionOnly` flag in the cancel payload.
This ensures the reservation is only released if authorization is still pending.

### Cancel after a partial capture

You should always release any funds you don't plan to capture, as soon as possible.
After a partial capture, cancelling the payment will release the remaining reserved amount, so the customer can use those funds for other purposes.

Use the [`cancel`](https://developer.vippsmobilepay.com/redocusaurus/epayment-swagger-id.yaml) endpoint to release any remaining funds.

> Cancelling after a partial capture will always release the *entire* not-yet-captured amount for the payment.
> This action is irreversible.

**Example**

Suppose you have a payment with the following aggregates:

```json
{
  "aggregate": {
    "authorizedAmount": { "currency": "NOK", "value": 1000 },
    "cancelledAmount": { "currency": "NOK", "value": 0 },
    "capturedAmount": { "currency": "NOK", "value": 250 },
    "refundedAmount": { "currency": "NOK", "value": 0 }
  }
}
```

To release the remaining funds, call
[`POST:/epayment/v1/payments/{reference}/cancel`][cancel-payment-endpoint]
as usual.

After cancellation, the `aggregate` is updated and the remaining funds are released to the customer's bank account:

```json
{
  "aggregate": {
    "authorizedAmount": { "currency": "NOK", "value": 1000 },
    "cancelledAmount": { "currency": "NOK", "value": 750 },
    "capturedAmount": { "currency": "NOK", "value": 250 },
    "refundedAmount": { "currency": "NOK", "value": 0 }
  }
}
```

[cancel-payment-endpoint]: https://developer.vippsmobilepay.com/redocusaurus/epayment-swagger-id.yaml

> **Full site overview:** For every page in this documentation, read [https://developer.vippsmobilepay.com/llms.txt](https://developer.vippsmobilepay.com/llms.txt).