Debicheck Mandate Amendments

Overview

Debicheck mandates can be amended using the paymentConsentRequestAmend mutation.

Before proceeding with an amendment, please note the following fields may not be amended and will require a new mandate (PaymentConsentRequest) to be created.

• Collection frequency
• Debtor bank branch code or bank
• Combination of debtor identification number and bank account number
• Contract reference (unless no collections have been made).

Amending the following fields will require re-authentication by the customer:

FIELD NAME	REMARKS
Maximum collection amount	If Maximum Collection Amount is amended and Adjustment Category = “N”- “Never”, then re-authentication is required.
First collection date	If the First Collection Date is amended then the debtor must authorise
Initial Amount	If the Initial Amount is amended then the debtor must authorise
Instalment Amount and Adjustment Category	If the Instalment Amount is amended and the Adjustment Category = N - Never, then re-authentication is required.
Collection Day	If the collectionDay is amended, then the debtor must reauthenticate
Creditor Short name	If the shortname is amendment then the debtor must reauthenticate.
Day adjustment allowed	If the dayAdjustmentAllowed is amended, then the debtor must reauthenticate.
Adjustment amount	If the adjustmentAmount is amended, then the debtor must reauthenticate.
Adjustment rate	If the adjustmentRate is amended, then the debtor must reauthenticate.

Amending the following fields will trigger a notification to the customer, but they will not be required to authenticate:

MANDATE FIELD	NOTES
Maximum collection amount	If Adjustment Category on initial mandate is not set to Never , then maximum collection amount can be amended and a notification is sent to the customer.
Instalment amount and Adjustment Category	If Adjustment Category on initial mandate is not set to Never , then instalment amount can be amended by the exact amount of rate that was specified under Adjusment amount or Adjustment rate on the initial mandate. Otherwise, it can only be amended as per the Adjustment category i.e. Quarterly, Bi-annually, Annually. A notification is sent to the customer.
Account Tracking	A notification is sent to the customer.
Contract reference	Can only be amended before the first collection is made. Otherwise, a new mandate is required. A notification is sent to the customer.
Creditor Name	A notification is sent to the customer.
Debtor Name	A notification is sent to the customer.
Debtor Identification	A notification is sent to the customer.
Debtor account type	A notification is sent to the customer.
Debtor account number	If the account number exists in the same bank, then a notification would be sent to customer. Otherwise, a new mandate is required

Amendment Example Mutation

info

The amendmentRequests property on the consent details will contain a history of amendment requests and their associated status.

This property can be used to determine the outcome of an amendment, and can be expected on a webhook when the amendment request succeed or fails.

The following values for $reason field are accepted:

Reason code	Description
CUSTOMER_REQUEST	Request by customer
INITIATOR_REQUEST	Amendment requested by initiating party
GENERAL	Reason has not been specified by customer

In case of failed validation, the below error codes would be returned:

Error	Description
Invalid mandate	Mandate with given originalContractReference not found for the client
Inactive mandate	Mandate is revoked or expired
Invalid amendment request	Only fields mentioned above can be amended. Would require a new mandate.
Invalid instalment amount	Instalment amount can be amended by exact value specified under adjustmentAmount or adjustmentRate on initial mandate.

Webhooks

When amendment requests are either successful or failed, a webhook will be sent with the status, and amended fields or failure reason respectively. Please see the webhooks section in the integration guide for information on integrating webhooks.

Example webhook payload for a success case

{
  "datetime": "2023-05-10T12:22:42.865Z",
  "id": "consent-request:status:success:cb6f2bd9-5c88-41f9-82a5-a45a24610bf6",
  "type": "consent-request-status",
  "data": {
    "createdAt": "2023-06-11T11:52:49.230Z",
    "id": "cmVjdXJyaW5nUGF5bWVudENvbnNlbnRSZXF1ZXN0L2NiNmYyYmQ5LTVjODgtNDFmOS04MmE1LWE0NWEyNDYxMGJmNg==",
    "action": "AMENDMENT",
    "outcome": "SUCCESS",
    "type": "DEBICHECK",
    "amendedFields": {
      "collectionDay": 7
    },
    "updatedAt": "2023-06-21T11:52:49.230Z"
  }
}

Example webhook payload for a failure case

{
  "datetime": "2023-05-10T12:22:42.865Z",
  "id": "consent-request:status:success:cb6f2bd9-5c88-41f9-82a5-a45a24610bf6",
  "type": "consent-request-status",
  "data": {
    "createdAt": "2023-06-11T11:52:49.230Z",
    "id": "cmVjdXJyaW5nUGF5bWVudENvbnNlbnRSZXF1ZXN0L2NiNmYyYmQ5LTVjODgtNDFmOS04MmE1LWE0NWEyNDYxMGJmNg==",
    "action": "AMENDMENT",
    "status": "FAILED",
    "type": "DEBICHECK",
    "amendedFields": {
      "collectionDay": 7
    },
    "updatedAt": "2023-06-21T11:52:49.230Z"
  }
}