Cancel and Unblock

Introduction

Financial Institutions use payment blocks as a way of stopping payments towards subscription merchants. These payment blocks are carried out by the card schemes (Visa and Mastercard) through their respective APIs (VSPS and PCS). The duration of the payment block is defined by the financial institution and can be in place for a maximum duration of 13 months. Payment blocks ensure that no more payments can be taken by the subscription merchant from the customers card, and while this is a protective measure for customers, it also prevents them from resubscribing to the subscription merchant in the 13 month period unless the block is removed. This results in loss of revenue for the subscription merchant.

Real-time cancellations with Minna's Merchant API ensures that a customers card is no longer blocked towards you as a subscription merchant. Minna in collaboration with the card schemes and the issuing retail bank will facilitate the removal of the block on the card for all successful cancellations. If the cancellation is unsuccessful, the block will remain in place for 13 months.

A removal of the block on the card towards the subscription merchant means that the user can re-subscribe to the merchant at a later date with the same card without any errors.

26822682

Merchant API - Cancel and Unblock (User interface)

16521652

Merchant API - Successful cancellation

📘

What is a successful cancellation?

A cancellation request sent by Minna to the subscription merchant that ensures that the subscription merchant was able to identify the customer from the request payload and was able to perform a cancellation of the contract.

A successful cancellation contractually binds the subscription merchant to cancel the contract of the customer and ensure that no more payments are taken from the customer.

Cancellation request

An event with eventType set to cancellation.requested will be sent every time a user requests a cancellation. The data object will contain information about what is being cancelled. Please see a description of the fields sent as part of the request payload in the section under Customer identifiers

If a relevant contract can be found from the given data, the contract is expected to be cancelled promptly.

Payload example

This is what an entire cancellation request might look like:

{
  "id": "eea6bf1c-0ae9-45af-88be-15a90cb8e708",
  "createdAt": "2018-12-03T10:15:30+01:00",
  "eventType": "cancellation.requested",
  "data": {
    "id": "ffffffff-0ae9-45af-88be-15a90cb8e708",
    "proof": {
      "mimeType": "application/pdf",
      "payload": "VGhlIGNha2UgaXMgYSBsaWU="
    },
    "desiredCancellationDate": "2019-03-03T10:15:30+01:00",
    "market": "UnitedKingdom",
    "merchantName": "ABC Inc.",
    "name": {
      "full": "John Adam Smith",
      "first": "John Adam",
      "last": "Smith"
    },
    "phoneNumber": "+3123456789",
    "customerId": "123456789-4",
    "paymentCardLast4Digits": "1234",
    "address": {
      "street": "Main Street 1",
      "city": "Smallville",
      "postalCode": "90210"
    },
    "emailAddress": "[email protected]"
  }
}

📘

Note

The shape of the object above seldom changes, but could occasionally be updated based on requirements from the merchants we work with.

Tip: If your business only looks at specific fields rather than validating the entire shape of the object, then the updates we make should not impact your integration. Any major changes will be published in a new version of the API and communicated on this page.

Cancellation response

When a cancellation request is received, the webhook should respond with a cancellation outcome. Any response except the ones listed below will cause the webhook to fail. If a backup channel is set up within Minna's system (e.g. emails) the cancellation will be retried via that channel.

🚧

Response structure

When returning the response back to Minna, please ensure that the shape of the object is as described in this documentation.

Cancellation outcomes

Accepted
The cancellation was accepted and is effective immediately or at the end of the current billing cycle. No further billing will occur on the user's account.

{
  "outcome": "Accepted"
}

AlreadyCancelled
The users contract has already been cancelled in the past. cancellationDate is the date on which the subscription was cancelled. The statusMessage is optional.

{
  "outcome": "AlreadyCancelled",
  "cancellationDate": "2019-03-03T10:15:30+01:00",
  "statusMessage": "This subscription has already been cancelled"
}

BindingPeriod
If a subscription is in a binding period and cannot be cancelled, then return the following response where cancellationDate is the date until which the subscription is under a binding contract. The statusMessage is optional.

{
  "outcome": "BindingPeriod",
  "cancellationDate": "2019-03-03T10:15:30+01:00",
  "statusMessage": "This subscription cannot be cancelled as it is in binding period"
}

Deferred
If a user has requested a cancellation to be performed in the future, then return the following response where reason is always "UserRequested" and the endDate is the date on which the cancellation will be executed.

{
  "outcome": "Deferred",
  "reason": "UserRequested",
  "endDate": "2019-03-03T10:15:30+01:00"
}

InconsistentData
If you are using more than 1 field from the request payload for finding the user in your system, then you can use this outcome to indicate back us that the cancellation was unsuccessful as there was only a partial match on the field. The statusMessage is optional.

{
  "outcome": "InconsistentData",
  "statusMessage": "Could not find the user"
}

UserNotFound
If a user or subscription cannot be found based on the information in the request payload, then you can use this outcome. The statusMessage is optional.

{
  "outcome": "UserNotFound",
  "statusMessage": "Could not find the user"
}

📘

Ready to get started?

Start by registering your endpoint using the API key to receive cancellation events. Fill out this form to get access to your API key.


Did this page help you?