Sent to request termination of an existing mandate.
Holds a point-to-point unique message identification string as well as a message's creation date time.
The date and time at which the message was created, in senders local timezone or UTC. The date must be formatted as defined by date-time in RFC3339
A list of key-value pairs to support adding any supplementary/additional data to an Electrum Regulated Payments API message.
This model is the basic representation of a Party. It is expanded on depending on whether the party is a person or an organisation.
Designates which scheme a mandate operation is associated with and describes scheme-specific information for the mandate operation where relevant.
Identifies the scheme used for the payment
ZA_RTC: South African Realtime Clearing scheme.ZA_RPP: South African Realtime Payments Platform scheme.ZA_EFT: South African Electronic Funds Transfer scheme.ZA_AC: South African Authenticated Collections scheme.ZA_RMS: South African Registered Mandate Service scheme.CBPR_PLUS: Cross-Border Payments and Reporting Plus.TCIB: Transactions Cleared on an Immediate Basis scheme.
South Africa specific supplementary data fields. These fields supplement the core mandate structure with local requirements.
Identifies the type of mandate amendment being requested. This is required for every MandateAmendmentRequest, and is echoed on the acceptance report for that request. It is not applicable to any other mandate operation and should be omitted from those.
Cession and assignment is carried by the same amendment operation as a routine amendment, but it is an operationally a different workflow, so it is stated explicitly here rather than being inferred from the local instrument code.
CONTRACT_AMENDMENT: A routine (business as usual) amendment to the terms of an existing mandate.CESSION_AND_ASSIGNMENT: The transfer of a mandate, or a book of mandates, to a different creditor, sponsoring bank or ultimate creditor. Only administrative and creditor fields may be changed - the core contract and payment terms cannot be modified during a cession. Cession and assignment additionally requires prior approval.
Indicates the delivery and authentication mechanism of the mandate transaction.
In the ZA_AC scheme, this field dictates the specific Transaction Type (TT) processing rules that will be applied:
REAL_TIME: Maps toTT1(non-card). The mandate request is routed over the real-time interbank switch without an upfront authentication key. Note: The actual Payer authorisation might be immediate (e.g., 120-second USSD timeout) or delayed (until the end of the day), but the routing type remains REAL_TIME.PREAUTH: Maps toTT3(Card Present). Indicates the Payer has already been authenticated via a prior card-and-PIN transaction at the point of interaction. Mandates using this type must include the resulting Message Authentication Code (MAC) in the request payload.BATCH: Maps toTT2. The mandate request is submitted via delayed bulk file processing.NOT_APPLICABLE: Debtor authentication is not required for this action (e.g.MandateInformationRequest).
The Mandate Reference Number (MRN) assigned by the debtor bank upon mandate acceptance. This is the official, unique industry-wide identification number for the mandate that is unique for the mandate's entire lifecycle (including time in archives).
It is returned in the acceptance report and must be included in subsequent mandate amendment, and suspension requests.
Not to be confused with mandateIdentification (the creditor's internal ID) or mandateRequestTransactionIdentifier (MRTI).
Structure (22 characters):
- Bank Number (4 numeric): The 4-digit identifier of the Debtor Bank.
- Mandate Creation Date (8 numeric): The date the mandate was successfully registered, formatted strictly as
YYYYMMDD. - Free Format (10 alphanumeric): A unique identifier or sequence generated by the Debtor Bank.
Mandate Request Transaction Identifier (MRTI) A unique transaction identifier used for matching multiple messages to a single transaction. This identifier is created for each new mandate request to uniquely identify the transaction within the Authenticated Collections scheme.
Important: Usage of mandateRequestTransactionIdentifier**.
- If the client is the host of the mandate register and is the source of truth for mandate state the client is required to always populate the
MRTI. The format is validated and the providedMRTIis used by Electrum. - If Electrum is the source of truth for mandate state the
MRTIshould not be provided by the client when initiating new mandate transactions; Electrum will generate a compliantMRTIautomatically which will be echoed back to the client.
Structure (23 characters):
- Positions 1–4 (4 numeric): Originating bank number. Must be a valid, registered bank.
- Positions 5–14 (10 alphanumeric): Origination date in the format
YYYY-MM-DD. Must be a valid date. - Positions 15–23 (9 numeric): Mandate sequence number. Unique within the bank and date.
Lifecycle behaviour:
- Mandate Initiation Request: The originating bank creates a new, unique
MRTIfor the initiation request. If not provided by the client, Electrum generates one automatically. - Mandate Amendment Request: A new, unique
MRTIis required for the amendment request. If not provided by the client, Electrum generates one automatically. The amendment is linked back to the original mandate using the Mandate Reference Number (MRN). - Mandate Cancellation Request:
- In-flight cancellation: If cancelling a mandate request that is still in-flight (e.g. awaiting debtor authentication), the
MRTImust exactly match theMRTIof the in-flight request being cancelled. If not provided, Electrum handles this automatically by retrieving theMRTIof the in-flight transaction. - Active mandate cancellation: If the mandate is already fully registered and active, a new, unique
MRTImust be issued for the cancellation request. If not provided, Electrum determines the mandate state and applies the correct rule automatically.
- In-flight cancellation: If cancelling a mandate request that is still in-flight (e.g. awaiting debtor authentication), the
- Mandate Acceptance Report: The response echoes back the
MRTIfrom the request being responded to. For API-level correlation, clients useoriginalMessageIdentifiers.messageIdentificationinstead. - Mandate Status Report: The status report echoes back the
MRTIfrom the request being reported on. For API-level correlation, clients useoriginalMessageIdentifiers.messageIdentificationinstead.
Validation rules enforced by the scheme:
- Must not be blank or spaces.
- The bank number (positions 1–4) must be a valid, registered bank.
- The date (positions 5–14) must be a valid calendar date.
- Must conform to the 23-character structured format.
- Must be unique at the time of request origination.
Contains the core details of the mandate cancellation request.
Field Usage Guidelines:
originalMessageInformation: ONLY required for in-flight cancellations (when a mandate initiation or amendment is still pending or has timed out). It identifies the specific pending message to cancel.
Provides details about the reason for a mandate cancellation.
Field Usage Guidelines: reason: For South African Mandate Schemes the reason for the cancellation is specified as one of the below PROPRIETARY values:
CEXP- Contract expired.MACN- Cancellation of Mandate Amendment (Strictly used when cancelling an in-flight MandateAmendmentRequest).MICN- Cancellation of Mandate Initiation (Strictly used when cancelling an in-flight MandateInitiationRequest).MCES- Mandate Cancelled due to early settlement.MCFR- Mandate Cancellation due to Fraud.MD17- Cancellation/amendment requested by the creditor.
This model is the basic representation of a Party. It is expanded on depending on whether the party is a person or an organisation.
Specifies the reason for a mandate action (amendment, cancellation, rejection).
Identifies the value as being a pre-defined code. Always CODE.
AC01- IncorrectAccountNumberAC04- ClosedAccountNumberAC06- BlockedAccountAG01- TransactionForbiddenAG02- InvalidBankOperationCodeAM02- NotAllowedAmountAM03- NotAllowedCurrencyAM05- DuplicationBE01- InconsistenWithEndCustomerBE04- MissingCreditorAddressBE05- UnrecognisedInitiatingPartyBE06- UnknownEndCustomerBE07- MissingDebtorAddressDT01- InvalidDateFF01- InvalidFileFormatMD01- NoMandateMD02- MissingMandatoryInformationInMandateMD07- EndCustomerDeceasedMD08- NoMandateServiceByAgentMD09- NoMandateServiceOnCustomerMD10- NoMandateServiceForSpecifiedMD11- UnrecognisedAgentMD12- NotUniqueMandateReferenceMD13- IncorrectCustomerAuthenticationMD14- IncorrectAgentMD15- IncorrectCurrencyMD16- RequestedByCustomerMD17- RequestedByInitiatingPartyMD18- RequestedByInitiatingPartyAndCustomerMD19- MandateCancelledDueToEarlySettlementMD20- MandateExpiredMD21- MandateCancelledDueToFraudMD22- MandateInitiationCancelledMD23- MandateAmendmentCancelledMS02- NotSpecifiedReasonCustomerGeneratedMS03- NotSpecifiedReasonAgentGeneratedNARR- NarrativeRC01- BankIdentifierIncorrectRF01- NotUniqueTransactionReferenceRR01- MissingDebtorAccountOrIdentificationRR02- MissingDebtorNameOrAddressRR03- MissingCreditorNameOrAddressRR04- RegulatoryReasonSL01- SpecificServiceOfferedByDebtorAgentSL11- CreditorNotOnWhitelistOfDebtorSL12- CreditorOnBlacklistOfDebtorSL13- MaximumNumberOfDirectDebitTransactionsExceededSL14- MaximumDirectDebitTransactionAmountExceeded
Reference to an original mandate. The mandate may be identified either by a reference (originalMandateIdentification) or by the full details of the mandate as it currently stands (originalMandate). At least one of the two must be provided.
Which of the two is expected depends on who hosts the mandate register:
- Electrum hosts the mandate register:
originalMandateIdentificationon its own is sufficient for mandate amendment, cancellation and suspension requests. Electrum identifies the mandate from the reference and enriches the request with the full mandate details the scheme requires before forwarding it. Partners are not required to perform a mandate information request first in order to construct these requests, although they may still do so if they need to see the current state of the mandate. - The partner hosts the mandate register: the partner is the source of truth for mandate state, so the full
originalMandatemust be provided.
Core mandate data structure containing all the details of a direct debit mandate.
Identifies the original mandate-management message being referenced or responded to. For MandateInformationRequest, this block is optional on the partner request — Electrum will populate it from the latest message recorded against the mandate before forwarding to the scheme.
{ "messageIdentifiers": { "creationDateTime": "2019-08-24T14:15:22Z", "messageIdentification": "string" }, "supplementaryData": { "property1": "string", "property2": "string" }, "initiatingParty": { "address": { … }, "contactDetails": { … }, "countryOfResidence": "string", "identification": { … }, "knownAsName": "string", "legalName": "string" }, "instructedAgent": { "additionalIdentifications": [ … ], "address": { … }, "bicfi": "string", "branch": { … }, "clearingSystemMemberId": { … }, "companyRegistration": "string", "lei": "string", "memberId": "string", "name": "string" }, "instructingAgent": { "additionalIdentifications": [ … ], "address": { … }, "bicfi": "string", "branch": { … }, "clearingSystemMemberId": { … }, "companyRegistration": "string", "lei": "string", "memberId": "string", "name": "string" }, "paymentScheme": { "schema": "ZA_RTC", "schemeData": { … } }, "schema": "MandateCancellationRequest", "underlyingCancellationDetails": { "cancellationReason": { … }, "originalMandate": { … }, "originalMessageInformation": { … } } }