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

Merchant Outreach - Sending the cancellationMerchant Outreach - Sending the 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 questionscancellation questions - User inputs required in order to carry out a cancellation request for a specific merchant. 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 elementsform elements - A form element is a container for different types of input elements, such as: text fields, checkboxes, radio buttons, submit buttons, etc. 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 AttorneyLetter of Attorney - Agreement signed between user and Minna Technologies for Minna Technologies to act on behalf of the user. 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 ServiceVisa Stop Payment Service - The Visa Stop Payment Service (VSPS) enables Visa card issuers to stop card-on-file payments (including recurring and instalment) from being authorized, cleared, and settled through VisaNet (VSPS)
    • Client ID and Bank Identification NumberBank Identification Number - A unique 6 or 8-digit number assigned by ISO to Visa and then by Visa to the processors, acquirers, issuers and other financial institutions involved in the interchange process; it is the first six or eight digits of the cardholder’s account number. Also known as Issuer Identification Number (IIN). (BIN) are configured on the Visa developer portal.
  • MasterCard - Payments Cancel ServicePayments Cancel Service - A service Mastercard provides for cancelling payments (PCS)
    • Customer Interface SpecificationCustomer Interface Specification - A number MasterCard gives to a project when it is opened. Must be allocated using a process described in PCS guide (sending emails to the particular list of people). (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 NumberPrimary Account Number - Primary Account Number (PAN) is known as a payment card number or simply a card number, and is the card identifier found on payment cards, such as credit cards and debit cards. PAN is a key piece of cardholder data (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
    • CardAcceptorIdCardAcceptorId - The Card Acceptor ID (CAID) is a unique identifier number for the originator of transfers (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 AssociationInterbank Card Association - A four-digit number assigned by MasterCard to a financial institution, third-party processor or other members to identify the member in transactions. Usually located by the expiration on the credit card. The ICA number is converted to identify the first four to six digits of the card number. (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 EncryptionJSON Web Encryption - JSON Web Encryption (JWE) represents encrypted content using JSON-based data structures, described in https://www.rfc-editor.org/info/rfc7516 (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 StandardAdvanced Encryption Standard - Advanced Encryption Standard (AES) is a specification for the encryption data using block ciphers described in ISO/IEC 18033-3 (AES), Galois Counter ModeGalois Counter Mode - Galois Counter Mode is a mode of operation for symmetric-key cryptographic block ciphers such as AES (GCM) with 128 bit key size will be used for message encryption. The encryption of keys is supported using RSA Optimal Asymmetric Encryption PaddingRSA Optimal Asymmetric Encryption Padding - RSA Optimal Asymmetric Encryption Padding (OAEP) is a padding scheme often used together with RSA (Rivest–Shamir–Adleman) public-key cryptosystem based on large prime numbers (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.

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

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 status

Description

AlreadyCancelled.outcomeName

The merchant informed us that the contract was already cancelled.

Cancelled.outcomeName

The cancellation request has been accepted and the contract will be cancelled.

ConfirmedByUser.outcomeName

The user let us know that the contract is cancelled via insight card while the state is set to WaitingForUserInput.

HasBindingPeriod.outcomeName

The user has binding period.

ManuallyClosed.outcomeName

We manually closed the cancellation, and no email about the outcome will be sent to the user.

NoResponseFromServiceProvider.outcomeName

The merchant has not answered the cancellation

NoResponseFromUser.outcomeName

We were missing some information from the user and tried to contact the user but got no response.

NoSuchAccount.outcomeName

Merchant did not find an account that matched the cancellation info.

NotACancellableSubscription.outcomeName

The subscription was not a cancellable subscription. Can happen when the user adds a merchant by "free text".

PayingThroughThirdParty.outcomeName

The subscription is payed through a third party (AppStore, Google Play etc)

UserDeleted.outcomeName

If the user is deleted, we remove the contract and abort the cancellation.

UserWithdrawn.outcomeName

The user regretted the cancellation.

WithdrawalSentToServiceProvider.outcomeName

The 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:

<MO outcome screen><MO outcome screen>

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:

<Merchant API outcome screens: Successful and Unsuccessful><Merchant API outcome screens: Successful and Unsuccessful>

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.


Did this page help you?