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 Dateis amended then the debtor must authorise | 
| Initial Amount | If the Initial Amountis amended then the debtor must authorise | 
| Instalment Amount and Adjustment Category | If the Instalment Amountis amended and theAdjustment Category= N - Never, then re-authentication is required. | 
| Collection Day | If the collectionDayis amended, then the debtor must reauthenticate | 
| Creditor Short name | If the shortnameis amendment then the debtor must reauthenticate. | 
| Day adjustment allowed | If the dayAdjustmentAllowedis amended, then the debtor must reauthenticate. | 
| Adjustment amount | If the adjustmentAmountis amended, then the debtor must reauthenticate. | 
| Adjustment rate | If the adjustmentRateis 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 Categoryon initial mandate is not set toNever, then maximum collection amount can be amended and a notification is sent to the customer. | 
| Instalment amount and Adjustment Category | If Adjustment Categoryon initial mandate is not set toNever, then instalment amount can be amended by the exact amount of rate that was specified underAdjusment amountorAdjustment rateon the initial mandate. Otherwise, it can only be amended as per theAdjustment categoryi.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
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 code | Description | 
|---|---|
| CUSTOMER_REQUEST | Request by customer | 
| INITIATOR_REQUEST | Amendment requested by initiating party | 
| GENERAL | Reason has not been specified by customer | 
| UNSUSPEND_WITH_CHANGE | Unsuspend a mandate with changes | 
| UNSUSPEND_WITHOUT_CHANGE | Unsuspend an unchanged mandate | 
| UPGRADE_RM_WITH_CHANGES | Upgrade registeredMandatewith changes | 
| UPGRADE_RM_WITHOUT_CHANGES | Upgrade registeredMandatewithout changes | 
In case of failed validation, the below error codes would be returned:
| Error | Description | 
|---|---|
| BAD_USER_INPUT | Mandate with given consentRequestIdnot found for the client | 
| NONCE_DUPLICATE | Nonce provided is already in used | 
| BAD_USER_INPUT | Failed 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,
      }
    }
  }
}