Cancel Native

Introduction

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

15681568

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.

Checkbox

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.

Encryption

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:

{"alg":"RSA-OAEP-256","enc":"A128GCM"}

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.

-----BEGIN CERTIFICATE-----
MIID/DCCAuQCCQDs7Kvhh6VtOjANBgkqhkiG9w0BAQsFADCBvzELMAkGA1UEBhMC
U0UxFDASBgNVBAgMC0fDg8K2dGVib3JnMRQwEgYDVQQHDAtHw4PCtnRlYm9yZzEb
MBkGA1UECgwSTWlubmEgVGVjaG5vbG9naWVzMREwDwYDVQQLDAhQYXltZW50czEn
MCUGA1UEAwweaHR0cHM6Ly9taW5uYXRlY2hub2xvZ2llcy5jb20vMSswKQYJKoZI
hvcNAQkBFhxkZXZlbG9wZXItc3VwcG9ydEBtaW5uYS50ZWNoMB4XDTE5MTEyMDE1
MzIyNloXDTIwMTExOTE1MzIyNlowgb8xCzAJBgNVBAYTAlNFMRQwEgYDVQQIDAtH
w4PCtnRlYm9yZzEUMBIGA1UEBwwLR8ODwrZ0ZWJvcmcxGzAZBgNVBAoMEk1pbm5h
IFRlY2hub2xvZ2llczERMA8GA1UECwwIUGF5bWVudHMxJzAlBgNVBAMMHmh0dHBz
Oi8vbWlubmF0ZWNobm9sb2dpZXMuY29tLzErMCkGCSqGSIb3DQEJARYcZGV2ZWxv
cGVyLXN1cHBvcnRAbWlubmEudGVjaDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCC
AQoCggEBAKQR3fnxZhVekLNylnMNmeXJktlCkPS1kJoBqNgec1EJIn/vxZhj4N40
GXFLbk+803Ias3WpYxALlWe3HzLIP+Vpe4Wrb5bpml8x/VIFftRgD2xBkWG7ij/j
ZukNGszcbCt4UuUjjd80sNx3p0vLBFFQICs1uzSDDg5vJ0PsG16Wx94wiHkfuD2Q
Td5Avw5NmxQ7gYsl8FYTSKeB13q6CWb1/kxyEKPMmILOZWljEw/0lL6KxKyuPTya
OqDiQzpoMWvNhHDtcMSPvUg08wzGg5OTJ4hvCC4Z/4WpAQv+lsVbeoQRCYC7rs/K
1rkmpzkg8OY8HQtjgYimNfIp6LIbp0MCAwEAATANBgkqhkiG9w0BAQsFAAOCAQEA
ZlxGud6wE5wev1BD4HmbWXN36G3lSFTvGmy7oXtd1FaVxByw0UO8Zmyql8C0QnOP
B/F/br1cbmw1wWryppUjArn0xXJhxiG5Exj0f13VBWBBbcL9cxr+P1+4NSgoi4ci
hmll8uNCkOax2vXvmWQe6WBaA7Q0Z2/LhKxiXDQwyfm2vkMY/KFoSLBTVvxgck2i
lshRyf3ofZpKhfq7rCEnsZGfLBjhKjza0Ndw3P4Xtn99qL1aWVvVeGOb6vnvfuaW
0DaJsrAcphB3rpeZcU5iPzkDv0hy9cKj2ITP8iacQMBJkvZsDMZEhka5K/ZSIQ/q
3cPOehF6aKjnGJOF5ke1PA==
-----END CERTIFICATE-----

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.

18231823

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

Response

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:

17811781

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:

24552455

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.