Cancel a payment

See Knowledge base: Cancellations for a general introduction to cancellations.

If you no longer wish to initiate settlement of the remaining funds on a payment then you should cancel the payment: POST:/epayment/v1/payments/{reference}/cancel. Cancelling a payment provides a good user experience and synchronizes the user's bank statement and the Vipps or MobilePay app payment overview with their expectations from a merchant.

A payment can be cancelled via the API or portal.vippsmobilepay.com at any point until the payment is fully captured. A cancellation will release any remaining authorized funds on the customers bank account.

Cancel via the API

The payment can be cancelled with POST:/epayment/v1/payments/{reference}/cancel.

Cancel before Authorization

If the payment has not yet reached the AUTHORIZED state, a cancellation by the merchant via the API will result in the TERMINATED state for the payment.

An example response for POST:/epayment/v1/payments/{reference}/cancel before authorization looks like this:

{
   "amount":{
      "currency":"NOK",
      "value":1000
   },
   "state":"TERMINATED",
   "aggregate":{
      "authorizedAmount":{
         "currency":"NOK",
         "value":0
      },
      "cancelledAmount":{
         "currency":"NOK",
         "value":1000
      },
      "capturedAmount":{
         "currency":"NOK",
         "value":0
      },
      "refundedAmount":{
         "currency":"NOK",
         "value":0
      }
   },
   "pspReference":"70b6ebe0-b400-4652-a3ea-70645e025035",
   "reference":"UNIQUE-PAYMENT-REFERENCE"
}

After the cancel is complete, a notification will be sent if a webhook is registered for the event epayments.payment.terminated.v1.

info

If a cancellation request arrives too late there is a chance that the user will have had time to authorize the payment. If you want to avoid releasing the reservation in this case you can set the cancelTransactionOnly flag in the cancel payload, which will ensure the payment is only canceled if the user has not yet authorized it.

Cancel after Authorization

If the payment has reached the AUTHORIZED state a POST:/epayment/v1/payments/{reference}/cancel request will not change the state of the payment, it will remain AUTHORIZED. However, the reserved amount from will be released (for the customer), and the aggregate object will reflect this with the cancelledAmount property.

An example response for a POST:/epayment/v1/payments/{reference}/cancel request after authorization looks like this:

{
   "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"
}

Even though the state of a payment doesn't change, a notification will be sent after the cancellation is processed, if a webhook is registered for the event epayments.payment.cancelled.v1.

info

It is not possible to cancel a payment while a user is actively authorizing the payment (e.g., the payment is under processing with the payment scheme, or the user is in a 3-D Secure session).

Cancel after a partial capture

Partial capture has limited availability for MobilePay. You must inquire during onboarding or contact customer service.

If you have captured a partial amount of the authorized amount and will not capture the remaining amount, you should release this. The cancel endpoint will do this for you.

note

Cancelling a payment will always cancel the entire remaining not-captured amount, this is irreversible.

The minimum amounts allowed are NOK 100 øre, DKK 1 øre, EUR 1 cent.

For example, to release the remaining funds of a payment with the following aggregate state:

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

Call POST:/epayment/v1/payments/{reference}/cancel as normal.

The aggregate would then be updated to reflect the modification and the funds release in the users bank account

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

For rate limiting questions, see: Rate limiting.