Cancel Native


Cancel is available as both WebUI and Native journey. This page will in detail go through the Native integration option. This guide will take you through the process of submitting a cancellation using Merchant Outreach, Block Payment, Intelligent Guide, and Merchant API. Depending on method the journey will vary but can be summarized in the following three steps:

  1. Determine if the Merchant can be cancelled
  2. Submit cancellation
  3. Notify user

First step is similar for all methods, step 2 and 3 will vary.

Step 1: Determine cancellation settings

Applicable for all methods
To determine the cancellation settings for a Merchant, please refer to the Subscription merchants API. Depending on what integration option you have chosen the process might vary.

Each Merchant can have the following cancellation settings:

  • Cancellable (Merchant Outreach)
  • Blockable (Block Payment)
  • CancellableWithGuide (Intelligent Guide)
  • CancellableWithMerchantApi (Merchant API)

Depending on the cancellation settings, different flows are needed for the user.

Step 2: Submit cancellation

Merchant Outreach and Merchant API

The following screens are needed in order to perform a Merchant Outreach cancellation


Merchant Outreach - Sending the cancellation

  1. Users will respond to cancellation questions
  2. User will sign a narrow agreement referred to as Power of Attorney (POA) or Agency Agreement for Minna to perform the cancellation on behalf of the user.
  3. Cancellation between Merchant Outreach and Merchant API differs:
    3.1. For merchants with setting Cancellable (Merchant Outreach), the cancellation is performed asynchronously which means the outcome of the cancellation is not determined in real-time.
    3.1. For merchants with setting CancellableWithMerchantApi (Merchant API), the cancellation is performed synchronously which means the outcome of the cancellation is determined in real-time.

To support these steps the following is needed:

Cancellation questions

The cancellation questions exist in order to collect the information required by the merchant to correctly identify and cancel the subscription on behalf of the user. Each question includes a question ID, which later needs to be provided together with the answer. The first action to take when a user wants to cancel a subscription is to request the form elements which the user is required to fill out. To retrieve the form elements, please refer to the API reference.

More information on form element types

The form element types includes:

  • Text paragraphs
  • Questions with the following answer types:
    • TextAnswer
      • General
      • EmailAddress
      • PhoneNumber
      • IntegerNumber
      • Date
    • MultipleChoiceAnswer
    • AddressAnswer

The text paragraph type is used to inform the user why information is collected, specific scenarios (such as blocking card payments) and similar. The text should be displayed as-is to the user.

Text answers contains a number of input types, which can be seen in the list above. The purpose of the input type is so that you can do client-side validation before sending answers to Minna. Common questions include asking for username, address, date when a subscription should be cancelled etc. Minna is aiming to collect as little information as possible from the user, while still being compliant with the requirements of the merchant.

Submit answers

The answers collected in the form elements should be sent to Minna for validation using the Prepare letter of attorney endpoint. If all validation passes, Minna will generate a Letter of Attorney. The Letter of Attorney is a legal document allowing Minna to carry out the cancellation on behalf of the user.

The payload of the successful response will contain a full Letter of Attorney text in markdown format. An ID for the Letter of Attorney will also be provided. This ID is important, as it needs to be included in the final request that submits the cancellation.

Submit cancellation

The user is required to sign the Letter of Attorney in order to submit the cancellation. There are three ways of signing a Letter of Attorney - all in line with EU legislation. The supported signing types are:

  • Checkbox
  • Written Signature
  • Digital Signature

After a cancellation is created, the cancellation ID should be saved in order to be able to query for updates easily.

Details on signature types

Details on all three signature types can be found in the API reference on how to create a cancellation.


Capture the consent from the user using a checkbox, which you will verify before submitting the cancellation.

Written signature

A written signature can be captured on screen, either allowing the user to sign using their finger and a touch screen for a mobile experience, or using a touchpad or mouse to sign in a desktop environment. You will capture the image containing the user's signature and send it as a base64 encoded string to Minna together with the appropriate mime type.

Digital signature

Digital signatures use strong customer authentication, which uses an external device to verify that the user is who they say they are and to record the signature upon signing a cancellation. You will capture the proof issued during the signature and send it as a base64 encoded string to Minna together with the appropriate mime type.

Block Payment

Integration Prerequisites

In order to perform payment blocks for Visa and MasterCard card networks, you will need to register with the respective network and set up the required information as stated below:

  • Visa - Visa Stop Payment Service (VSPS)
    • Client ID and Bank Identification Number (BIN) are configured on the Visa developer portal.
  • MasterCard - Payments Cancel Service (PCS)
    • Customer Interface Specification (CIS) number configured with a project on MasterCard systems.

Merchant identifiers and subscriber card information

To create a block payment cancellation the following transaction information needs to be provided:

  • Cardholder’s Primary Account Number (PAN) - PAN that the payment should be blocked for.
    Note that the PAN will be stored by Minna in a PCI-DSS-compliant way. It will only be stored for as long as it is required to perform the block payment request. After this it will be discarded.
  • A list of merchant identifiers
    • CardAcceptorId (CAID) - The Card Acceptor ID (CAID) is a unique identifier number for the originator of transfers. Typically, an ID is between 1 and 15 characters and is assigned for each store location. Applicable to Visa and MasterCard.
    • Merchant Names - Most important factor in cardholder recognition of transactions. We require the Merchant Name as provided by the payment network scheme, not cleansed or modified in any form. Only required for Visa.
    • Acquirer Interbank Card Association (ICA) number - A four to six digit identification assigned by MasterCard for use by a member to uniquely identify activity the member is responsible for. Only required for MasterCard.


In order to send the PAN securely to us, it should be encrypted with JSON Web Encryption (JWE). We recommend using an existing library for constructing the JWE. OpenID Foundation has an updated list of supported libraries.

The header of the JWE determines which algorithms should be used for content encryption. We expects the following header:


The header specifies that Advanced Encryption Standard (AES), Galois Counter Mode (GCM) with 128 bit key size will be used for message encryption. The encryption of keys is supported using RSA Optimal Asymmetric Encryption Padding (OAEP) with 2048 bit key size. When inserted into the payload, the PAN should be included as plain text, without any separators. Example payload, before encryption:

    primaryAccountNumber: 5174160958216138

There are additional fields available for other card details but these are all optional:

    primaryAccountNumber: 5174160958216138,
    firstName: John,
    lastName: Doe,
    expirationDate: 20/20,
    cvv: 000

For our sandbox environment the public key needed to create the JWE can be found below.


Submit Block

To submit a block for a subscription, issue a POST request. The blockData field contains a signed JWE and an identifier for the merchant. The block instruction will immediately be submitted by us and will be issued by Visa within 24 hours if the request was successful. However, we will immediately respond that the block was successfully placed in the cancellation object.


Technical flow for submitting a block payment (click on image for details)

Intelligent Guide

To implement Intelligent Guide, see this section.

Step 3: Notify user


When the cancellation has been created in any of the ways described above, Minna will respond with the newly created cancellation object.

Get cancellation status

To answer if a subscription has an ongoing cancellation and in what state it is, you will need to retrieve the most recent cancellation status. The table below describes each cancellation status.

Cancellation statusDescription
AlreadyCancelled.outcomeNameThe merchant informed us that the contract was already cancelled.
Cancelled.outcomeNameThe cancellation request has been accepted and the contract will be cancelled.
ConfirmedByUser.outcomeNameThe user let us know that the contract is cancelled via insight card while the state is set to WaitingForUserInput.
HasBindingPeriod.outcomeNameThe user has binding period.
ManuallyClosed.outcomeNameWe manually closed the cancellation, and no email about the outcome will be sent to the user.
NoResponseFromServiceProvider.outcomeNameThe merchant has not answered the cancellation
NoResponseFromUser.outcomeNameWe were missing some information from the user and tried to contact the user but got no response.
NoSuchAccount.outcomeNameMerchant did not find an account that matched the cancellation info.
NotACancellableSubscription.outcomeNameThe subscription was not a cancellable subscription. Can happen when the user adds a merchant by "free text".
PayingThroughThirdParty.outcomeNameThe subscription is payed through a third party (AppStore, Google Play etc)
UserDeleted.outcomeNameIf the user is deleted, we remove the contract and abort the cancellation.
UserWithdrawn.outcomeNameThe user regretted the cancellation.
WithdrawalSentToServiceProvider.outcomeNameThe cancellation is tied to a switch order, which failed in the order state. The cancellation is then revoked.

Cancellation outcome

Merchant Outreach

For merchants with the setting Cancellable (Merchant Outreach), the outcome of the cancellation request will vary depending on when the merchant takes action on the cancellation request. This could range between 0-5 days of submitting the request.

This means that the cancellation object will always be returned with the Cancellation status as Ongoing. In such time, the user is shown the following screen when the user takes the action:


Merchant API

For merchants with the setting CancellableWithMerchantApi (Merchant API) however, the outcome to the cancellation request is real-time.

This means that the user already has a decision on the cancellation request and the cancellation object will always be returned with any of the Cancellation statuses as listed above. The user is accordingly shown the relevant screen:


Withdraw Cancellation

A withdrawal can be done as long as the merchant has not acted upon the cancellation yet.

The user then need to withdraw their letter of attorney. This is done by calling the Withdraw cancellation endpoint. Minna will respond with status code 204 No Content to indicate that the request was processed successfully. The status of the cancellation object will change to Failed.