Skip to main content

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 NAMEREMARKS
Maximum collection amountIf Maximum Collection Amount is amended and Adjustment Category = “N”- “Never”, then re-authentication is required.
First collection dateIf the First Collection Date is amended then the debtor must authorise
Initial AmountIf the Initial Amount is amended then the debtor must authorise
Instalment Amount and Adjustment CategoryIf the Instalment Amount is amended and the Adjustment Category = N - Never, then re-authentication is required.
Collection DayIf the collectionDay is amended, then the debtor must reauthenticate
Creditor Short nameIf the shortname is amendment then the debtor must reauthenticate.
Day adjustment allowedIf the dayAdjustmentAllowed is amended, then the debtor must reauthenticate.
Adjustment amountIf the adjustmentAmount is amended, then the debtor must reauthenticate.
Adjustment rateIf 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 FIELDNOTES
Maximum collection amountIf 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 CategoryIf 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 TrackingA notification is sent to the customer.
Contract referenceCan only be amended before the first collection is made. Otherwise, a new mandate is required. A notification is sent to the customer.
Creditor NameA notification is sent to the customer.
Debtor NameA notification is sent to the customer.
Debtor IdentificationA notification is sent to the customer.
Debtor account typeA notification is sent to the customer.
Debtor account numberIf 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

Example response payload from AmendMandate mutation

{
"data": {
"paymentConsentRequestAmend": {
"id": "cGF5bWVudGNvbnNlbnRyZXF1ZXN0LzMwN2VhYTFmLTczMjQtNDAzNy05NjNiLWJlYWQ3NDY2YTNhNQ==",
"status": {
"__typename": "PaymentConsentGranted",
"date": "2025-10-08T10:33:14.747279+00:00"
},
"amendmentDetails": {
"authenticationChannel": "authRealtime",
"reason": "CUSTOMER_REQUEST",
"status": "PROCESSING",
"expectedAction": "Re-authentication required from customer",
"amendedFields": {
"collection": {
"collectionDay": 3,
"instalmentAmount": null,
"adjustmentAmount": null,
"adjustmentRate": null,
"amountAdjustmentFrequency": null,
"dayAdjustmentAllowed": null,
"firstCollectionAmount": null,
"firstCollectionDate": null,
"maximumCollectionAmount": null,
"trackingIndicator": null
},
"customer": {
"accountName": null,
"accountNumber": null,
"accountType": null,
"bankId": null,
"branchCode": null,
"email": null,
"fullName": null,
"identifyingDocument": null,
"phoneNumber": null
}
}
}
}
}
}

The following values for $reason field are accepted:

Reason codeDescription
CUSTOMER_REQUESTRequest by customer
INITIATOR_REQUESTAmendment requested by initiating party
GENERALReason has not been specified by customer
UNSUSPEND_WITH_CHANGEUnsuspend a mandate with changes
UNSUSPEND_WITHOUT_CHANGEUnsuspend an unchanged mandate
UPGRADE_RM_WITH_CHANGESUpgrade registeredMandate with changes
UPGRADE_RM_WITHOUT_CHANGESUpgrade registeredMandate without changes

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

ErrorDescription
BAD_USER_INPUTMandate with given consentRequestId not found for the client
NONCE_DUPLICATENonce provided is already in used
BAD_USER_INPUTFailed amendment validation rules.

Example error response payload from AmendMandate mutation

{
"errors": [
{
"message": "Invalid amendment consent inputs",
"locations": [
{
"line": 8,
"column": 3
}
],
"path": [
"paymentConsentRequestAmend"
],
"extensions": {
"errors": [
{
"property": "collection.instalmentAmount.quantity",
"description": "Collection Amount exceeds maximum."
}
],
"code": "BAD_USER_INPUT"
}
}
],
"data": null
}

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": "payment-consent-request:status:granted:cmVjdXJyaW5nUGF5bWVudENvbnNlbnRSZXF1ZXN0L2NiNmYyYmQ5LTVjODgtNDFmOS04MmE1LWE0NWEyNDYxMGJmNg==",
"type": "payment-consent-request",
"data": {
"createdAt": "2023-06-11T11:52:49.230Z",
"id": "cmVjdXJyaW5nUGF5bWVudENvbnNlbnRSZXF1ZXN0L2NiNmYyYmQ5LTVjODgtNDFmOS04MmE1LWE0NWEyNDYxMGJmNg==",
"nonce": "2296ad8e-15a4-4f73-a0ad-fb9f7194fb52",
"status": "GRANTED",
"type": "DEBICHECK",
"externalReference": "my-external-reference",
"updatedAt": "2023-06-21T11:52:49.230Z",
"metadata": {
"billingAddress": "{\"addressLine1\": \"123 Test Street\",\"addressLine2\": \"Apartment 4A\",\"city\": \"Cape Town\", \"province\": \"Western Cape\",\"postalCode\": \"8001\",\"country\": \"ZA\"}"
},
"statusReason": "CUSTOMER_REQUEST",
"consentDetails": {
"accountTracking": true,
"contractReference": "CONTRACT123",
"mandateReferenceNumber": "098765432123456789",
"authenticationChannel": "authRealtime",
"bankReasonCode": null,
"bankReasonDescription": null,
"collection": {
"dayAdjustmentAllowed": true,
"adjustmentAmount": 0,
"adjustmentRate": 0,
"amountAdjustmentFrequency": "annually",
"collectionDay": 7,
"debitValueType": "variable",
"collectionFrequency": "monthly",
"instalmentAmount": {
"quantity": 1000,
"currency": "ZAR"
},
"maximumCollectionAmount": {
"quantity": 1500,
"currency": "ZAR"
},
"firstCollectionDate": "2024-01-01",
"firstCollectionAmount": {
"quantity": 500,
"currency": "ZAR"
},
},
"customer": {
"phoneNumber": "082123456789",
"email": "john.doe@example.com",
"accountName": "John Doe Account",
"bankBranchCode": "123456",
"accountNumber": "1234567890",
"accountType": "CURRENT",
"fullName": "John Doe",
"identifyingDocument": {
"type": "IDENTITY_DOCUMENT",
"country": "ZA",
"number": "8001015009087"
},
},
"creditor": {
"schemeName": "CREDITOR_SCHEME_001",
"name": "Example Creditor Ltd",
"phoneNumber": "+27123456789",
"email": "creditor@example.com",
"accountNumber": "9876543210",
"branchCode": "654321",
"ultimateCreditorName": "Ultimate Creditor Name",
"ultimateCreditorAbbreviatedShortName": "UCN"
},
}
"amendment": {
"outcome": "ACCEPTED",
"reason": null,
"amendedFields": {
"collectionDay": 7,
}
}
}
}

Example webhook payload for a failure case

{
"datetime": "2023-05-10T12:22:42.865Z",
"id": "payment-consent-request:status:granted:cmVjdXJyaW5nUGF5bWVudENvbnNlbnRSZXF1ZXN0L2NiNmYyYmQ5LTVjODgtNDFmOS04MmE1LWE0NWEyNDYxMGJmNg==",
"type": "payment-consent-request",
"data": {
"createdAt": "2023-06-11T11:52:49.230Z",
"id": "cmVjdXJyaW5nUGF5bWVudENvbnNlbnRSZXF1ZXN0L2NiNmYyYmQ5LTVjODgtNDFmOS04MmE1LWE0NWEyNDYxMGJmNg==",
"nonce": "2296ad8e-15a4-4f73-a0ad-fb9f7194fb52",
"status": "GRANTED",
"type": "DEBICHECK",
"externalReference": "my-external-reference",
"updatedAt": "2023-06-21T11:52:49.230Z",
"metadata": {
"billingAddress": "{\"addressLine1\": \"123 Test Street\",\"addressLine2\": \"Apartment 4A\",\"city\": \"Cape Town\", \"province\": \"Western Cape\",\"postalCode\": \"8001\",\"country\": \"ZA\"}"
},
"statusReason": "CUSTOMER_REQUEST",
"consentDetails": {
"accountTracking": true,
"contractReference": "CONTRACT123",
"mandateReferenceNumber": "098765432123456789",
"authenticationChannel": "authRealtime",
"bankReasonCode": null,
"bankReasonDescription": null,
"collection": {
"dayAdjustmentAllowed": true,
"adjustmentAmount": 0,
"adjustmentRate": 0,
"amountAdjustmentFrequency": "annually",
"collectionDay": 1,
"debitValueType": "variable",
"collectionFrequency": "monthly",
"instalmentAmount": {
"quantity": 1000,
"currency": "ZAR"
},
"maximumCollectionAmount": {
"quantity": 1500,
"currency": "ZAR"
},
"firstCollectionDate": "2024-01-01",
"firstCollectionAmount": {
"quantity": 500,
"currency": "ZAR"
},
},
"customer": {
"phoneNumber": "082123456789",
"email": "john.doe@example.com",
"accountName": "John Doe Account",
"bankBranchCode": "123456",
"accountNumber": "1234567890",
"accountType": "CURRENT",
"fullName": "John Doe",
"identifyingDocument": {
"type": "IDENTITY_DOCUMENT",
"country": "ZA",
"number": "8001015009087"
},
},
"creditor": {
"schemeName": "CREDITOR_SCHEME_001",
"name": "Example Creditor Ltd",
"phoneNumber": "+27123456789",
"email": "creditor@example.com",
"accountNumber": "9876543210",
"branchCode": "654321",
"ultimateCreditorName": "Ultimate Creditor Name",
"ultimateCreditorAbbreviatedShortName": "UCN"
},
}
"amendment": {
"outcome": "REJECTED",
"reason": "Invalid amendment request",
"amendedFields": {
"collectionDay": 7,
}
}
}
}