Cancellations

A cancellation means stopping any further payments for the user and also cancelling the contract the user has with the merchant.

Cancellation data flow for Merchant APICancellation data flow for Merchant API

Cancellation data flow for Merchant API

Webhook events

Event

Description

cancellation.requested

A cancellation has been requested by a user. Details.

Cancellations will be placed by webhook events from Minna's system, and success or failure of cancellation will be reported back as return values to these calls.

Cancellation requested

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.

If a relevant contract can be found from the given data, the contract is expected to be cancelled promptly. It is acceptable to do this asynchronously if eventual consistency can be guaranteed. That is, you may regard a contract as cancelled if that process has been started on your side, even if the processing is not immediate.

Data fields

The data when requesting a cancellation will contain different data about the service being cancelled. This is further described in the section Cancellation request below.

Cancellation request

Cancellation data fields

All the fields described here except id, proof, portalUrl and market are to be regarded as optional. A cancellation request may contain them if the user has provided them or they are otherwise available.

While the fields below are currently standardized, other fields may be provided in the future, and your implementation should NOT treat unknown or undocumented fields as an error.

id

A unique UUID used to identify this cancellation. You may use this in communication with Minna in the future regarding this cancellation.

proof

A market-specific proof or other similar indication that this action was initiated by the user described. Depending on the market, the shape of this proof will vary. How to read/parse these proofs are outside the scope of this documentation. You should store this proof in order to maintain an audit trail of the user's consent to carry out this cancellation in case it is disputed at a later date. This proof usually contains personal data relating to the user, and this should be taken into account when storing it.

mimeType

Refers to the content type of this proof. Common types are application/xml and application/pdf, but the field is not limited to these content types.

payload

Refers to the data in this proof. If the content type describes binary data, this field will be base64-encoded.

desiredCancellationDate

Refers to when the user wants the cancellation to take effect. If this is present, you need to honor the date and time. If this is not present, the cancellation should take effect immediately.

market

Refers to the market this cancellation applies for. Note that due to differences in markets, other fields may differ between markets. Any such differences will be noted under the documentation for the field.

name

Refers to the field that contains the name of the user.

emailAddress

Refers to the field that contains the email address of the user.

phoneNumber

Refers to the phone number that is associated with this account, if available. This will be normalized to include country code and other prefixes, e.g. a United Kingdom mobile phone number will be sent on the form +447555123456.

customerId

Refers to the ID the user has within your system. This will be on the form that the user inputs when submitting a cancellation.

paymentCardLast4Digits

Refers to the last 4 digits of the credit/debit card that the account was registered with. Note that this is generally provided by the user, and may thus not necessarily match the card that was used for registering the original account, if the user specifies the wrong number.

address

Refers to the information about the user's address. This is, of course, highly market specific.

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",
    "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]"
  }
}

Responding to a cancellation request

When a cancellation request is received, the webhook should respond with a cancellation outcome. Cancellation outcomes are divided in two categories: successful and unsuccessful. 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.

Cancellation outcomes

Outcome

Category

Accepted

Successful

AlreadyCancelled

Successful

Deferred

Successful

BindingPeriod

Unsuccessful

InconsistentData

Unsuccessful

UserNotFound

Unsuccessful

Cancellation request responses

Responding successfully to a cancellation request without a payload implies that the cancellation was accepted. For a more granular control, the response should include a payload with a JSON object providing further information using any of the above mentioned outcomes. The response successful response status codes could be 200 OK, 202 Accepted or 204 No Content.

Below you find the description for the different possible responses for a successful cancellation request:

No payload, or "Accepted"

The cancellation was accepted and is effective immediately. No further billing will occur on the user's account.

Deferred

The cancellation was accepted and will be executed at a later date as requested by the user, for the specified reason.

UserRequested

The original request contained a request to defer cancellation to a later date, and that request is being honored.

Examples

HTTP response status code: 200
HTTP response body (application/json): {
  "outcome": "Deferred",
  "reason": "UserRequested",
  "endDate: "2019-03-03T10:15:30+01:00"
}

HTTP response status code: 202 
/* Responding with status code 200, 202 or 204 implicitly implies that the cancellation request was  accepted, and the payload could be omitted. */

404 Not Found

The user could not be found from the provided data. The response should contain additional details regarding the reason as well as any required data. An additional string may also be provided detailing what happened. This string may be presented to the user (but this is not guaranteed), and needs to be formatted as such (e.g. be in the correct language for the market etc).

If you have a scenario which you believe cannot be described using these errors, please contact Minna Technologies and we can work together to accommodate these scenarios.

Common fields in responses

cancellationDate

The date on which the cancellation will take effect, in ISO-8601 format.

statusMessage

Optional message to send to Minna regarding the status of the cancellation. This can be used for communicating additional details and for debugging if required.


Did this page help you?