The Electrum Regulated Payments API is an asynchronous API that allows partners to participate in various nationally regulated payment schemes.
As the Regulated Payments API is asynchronous, partners have a choice of how to integrate with Electrum:
Receiving transactional events via webhooks or API are equivalent, except that it may be more familiar or convenient to implement one style or the other.
This document describes the operations a partner must implement for Electrum to consume in order to complete the integration with the Electrum Regulated Payments API.
https://example.com/path/payments/partner-api/v1/
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.
{ "creationDateTime": "2019-08-24T14:15:22Z", "messageIdentification": "string", "messageNameIdentification": "string" }
Contains the details of the mandate amendment including the reason, amended mandate, and original mandate reference.
Core mandate data structure containing all the details of a direct debit mandate.
Defines adjustment rules for mandate amounts.
Identifies the specific mechanism or channel that the Paying Bank (Debtor Bank) uses to communicate with the Payer (Debtor) to obtain their authorisation for a mandate. This field may be missing on mandate initiation/amendment and should be populated by the debtor bank upon acceptance of the mandate
This model is the basic representation of a Party. It is expanded on depending on whether the party is a person or an organisation.
A code to identify a country, a dependency, or another area of particular geopolitical interest, on the basis of country names obtained from the United Nations (ISO 3166, Alpha-2 code).
The identification of a party, either a person or an organisation.
The name by which this party is commonly known in day to day use. For example, a shortening of their legal name or a nickname that they commonly use. This is "non-official". However, it is acceptable for this field to be set to the same as legalName.
Representation of an account for payment purposes. Note that at least one of identification or proxy is expected to be present.
This model is the basic representation of a Party. It is expanded on depending on whether the party is a person or an organisation.
This model is the basic representation of a Party. It is expanded on depending on whether the party is a person or an organisation.
A code to identify a country, a dependency, or another area of particular geopolitical interest, on the basis of country names obtained from the United Nations (ISO 3166, Alpha-2 code).
The identification of a party, either a person or an organisation.
The name by which this party is commonly known in day to day use. For example, a shortening of their legal name or a nickname that they commonly use. This is "non-official". However, it is acceptable for this field to be set to the same as legalName.
Representation of an account for payment purposes. Note that at least one of identification or proxy is expected to be present.
A code allocated to a financial or non-financial institution by the ISO 9362 Registration Authority as described in ISO 9362 Banking - Banking telecommunication messages - Business identifier code (BIC)
An organisation identified by a code allocated to a party as described in ISO 17442 Financial Services - Legal Entity Identifier (LEI).
Name by which an institution is known and which is usually used to identify that institution
A unique identifier assigned to a company or organisation by a duly appointed authority within a country.
Unique identification of the mandate, as assigned by the creditor. This field is used strictly by the Creditor for their own internal referencing and may be used to link collections to their related mandate. This is required for mandate initiations and cancellations.
Reference assigned to the mandate by the mandate management application. This is distinct from mandateIdentification (creditor's ID) and ZaMandatePaymentSchemeSupplementaryData.debtorBankMandateReference (debtor bank's reference).
Unique identification of the mandate request, as assigned by the creditor to the debtor when the underlying contract is concluded between the two parties. This field represents the Contract Reference Number. It appears on the debtor's bank statement to help them identify the deductions. This is required for mandate initiations and mandate cancellations.
Defines the frequency and duration of mandate collections.
Specifies the reason for a mandate action (amendment, cancellation, rejection).
Provides information to identify the underlying documents associated with the mandate
Indicates whether the mandate permits tracking for future collection instructions. Its exact meaning and relevance depend strictly on the mandate-management operation being performed:
1. Mandate Initiation & Amendment Requests
true) or revoked (false) for future collections against this mandate.2. Mandate Cancellation Requests
true: Instructs the clearing house to immediately cancel any active tracking records currently in the tracking queue for this mandate.false: Instructs the clearing house NOT to cancel records in tracking, allowing them to finish their tracking cycle despite the mandate being cancelled.3. Mandate Acceptance Reports
true or false) that was successfully saved to the Debtor Bank's Mandate Register.4. Mandate Suspensions & Information Requests
This model is the basic representation of a Party. It is expanded on depending on whether the party is a person or an organisation.
Provides details about the reason for a mandate amendment.
Field Usage Guidelines: reason: For South African Mandate Schemes the reason for the amendment is specified as one of the below PROPRIETARY values:
MD02 - Reason has not been specified by end consumer.MD16 - Requested by Customer..MD17 - Amendment requested by Initiating Party.MD19 - Unsuspend a Mandate with changes.MD20 - Unsuspend an unchanged Mandate.MD21 - Amendment with no changes to Mandate Information.MD22 - Amendment with changes to Mandate Information.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 - MaximumDirectDebitTransactionAmountExceededReference to an original mandate. The partner may identify the mandate using any of the following identifiers, depending on the context of the request and the information available. At least one of originalMandateIdentification for the original mandate, or originalMandate must be provided.
For mandate amendment, cancellation and suspension requests, originalMandate is required and the originalMandateIdentification cannot be used as the sole reference.
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.
{ "amendedMandate": { "adjustment": { … }, "authentication": { … }, "collectionAmount": { … }, "creditor": { … }, "creditorAccount": { … }, "creditorAgent": { … }, "creditorSchemeIdentification": { … }, "debtor": { … }, "debtorAccount": { … }, "debtorAgent": { … }, "firstCollectionAmount": { … }, "mandateIdentification": "string", "mandateReference": "string", "mandateRequestIdentification": "string", "maximumAmount": { … }, "occurrences": { … }, "reason": { … }, "referredDocument": [ … ], "trackingIndicator": true, "type": { … }, "ultimateCreditor": { … }, "ultimateDebtor": { … } }, "amendmentReason": { "additionalInformation": [ … ], "originator": { … }, "reason": { … } }, "originalMandate": { "originalMandate": { … }, "originalMandateIdentification": "string" }, "originalMessageInformation": { "creationDateTime": "2019-08-24T14:15:22Z", "messageIdentification": "string", "messageNameIdentification": "string" } }
A request to amend an existing mandate. Sent to request changes to the terms 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.South Africa specific supplementary data fields. These fields supplement the core mandate structure with local requirements.
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 to TT1 (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 to TT3 (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 to TT2. The mandate request is submitted via delayed bulk file processing.NOT_APPLICABLE: Debtor authentication is not required for this action (e.g. MandateInformationRequest).The Payer's preferred recurring day for collection from their bank account.
In the ZA_AC scheme, the Collection Day is a rigid, legally binding clearing rule that is strictly evaluated relative to the mandate's Frequency. The interpretation of this integer changes based on the frequency type:
Monthly, Quarterly, Bi-annually, Annually, Once-off: Values 1 to 30 represent the exact calendar day of the month. 99 strictly represents the "Last Day" of the month (e.g., automatically adjusting for February 28th/29th). Note: 31 is not a valid input.Weekly: Values 1 to 7 represent the day of the week (1 = Monday, 7 = Sunday).Fortnightly: Values 1 to 14 represent the day within the two-week cycle (1 to 7 for week one; 8 to 14 for week two).Monthly by Rule: Values map to specific occurrences (e.g., 1 = Last Monday, 7 = First Monday, 14 = 2nd Last Day).Interbank Validation Rules: The Debtor Bank is required to store this exact day in their Mandate Register. If the mandate's dateAdjustmentRule is set to 'N' (No), the Debtor Bank will strictly validate incoming collections against this day. If a collection's Action Date does not exactly match this collectionDay (or the immediately following Processing Day), the Debtor Bank will trigger an upfront rejection.
Note: According to clearing rules, Debtor Banks are only required to enforce this strict date validation on Weekly and Monthly frequencies.
This dictates strict interbank validation rules for how collection amounts are calculated, capped, and adjusted over the life of the mandate.
The rules for each type are:
FIXED: Used for contracts where an upfront, calculated Instalment Amount is the basis for normal collections. Regular collections are strictly validated and cannot exceed this Instalment Amount. The Adjustment Category for a fixed mandate must strictly be 'NEVR' (Never).VARIABLE: Used for contracts where an upfront Instalment Amount is calculated but can be amended by the Creditor based on pre-agreed variables, such as annual increases or interest rate changes. Regular collections cannot exceed the currently active Instalment Amount.USAGE_BASED: Used for contracts where the collection amount fluctuates depending on the Payer's usage of a product or service during the payment cycle. Unlike Fixed and Variable mandates, the regular Instalment Amount is optional, and interbank validation is instead performed strictly against a mandatory Maximum Collection Amount.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 (creditor's internal ID), mandateRequestTransactionIdentifier (MRTI), or mandateReference (mandate management app reference).
Structure (22 characters):
YYYYMMDD.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**.
MRTI. The format is validated and the provided MRTI is used by Electrum.MRTI should not be provided by the client when initiating new mandate transactions; Electrum will generate a compliant MRTI automatically which will be echoed back to the client.Structure (23 characters):
YYYY-MM-DD. Must be a valid date.Lifecycle behaviour:
MRTI for the initiation request. If not provided by the client, Electrum generates one automatically.MRTI is 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).MRTI must exactly match the MRTI of the in-flight request being cancelled. If not provided, Electrum handles this automatically by retrieving the MRTI of the in-flight transaction.MRTI must be issued for the cancellation request. If not provided, Electrum determines the mandate state and applies the correct rule automatically.MRTI from the request being responded to. For API-level correlation, clients use originalMessageIdentifiers.messageIdentification instead.MRTI from the request being reported on. For API-level correlation, clients use originalMessageIdentifiers.messageIdentification instead.Validation rules enforced by the scheme:
Contains the details of the mandate amendment including the reason, amended mandate, and original mandate reference.
Core mandate data structure containing all the details of a direct debit mandate.
Defines adjustment rules for mandate amounts.
Identifies the specific mechanism or channel that the Paying Bank (Debtor Bank) uses to communicate with the Payer (Debtor) to obtain their authorisation for a mandate. This field may be missing on mandate initiation/amendment and should be populated by the debtor bank upon acceptance of the mandate
This model is the basic representation of a Party. It is expanded on depending on whether the party is a person or an organisation.
A code to identify a country, a dependency, or another area of particular geopolitical interest, on the basis of country names obtained from the United Nations (ISO 3166, Alpha-2 code).
The identification of a party, either a person or an organisation.
The name by which this party is commonly known in day to day use. For example, a shortening of their legal name or a nickname that they commonly use. This is "non-official". However, it is acceptable for this field to be set to the same as legalName.
Representation of an account for payment purposes. Note that at least one of identification or proxy is expected to be present.
This model is the basic representation of a Party. It is expanded on depending on whether the party is a person or an organisation.
This model is the basic representation of a Party. It is expanded on depending on whether the party is a person or an organisation.
A code to identify a country, a dependency, or another area of particular geopolitical interest, on the basis of country names obtained from the United Nations (ISO 3166, Alpha-2 code).
The identification of a party, either a person or an organisation.
The name by which this party is commonly known in day to day use. For example, a shortening of their legal name or a nickname that they commonly use. This is "non-official". However, it is acceptable for this field to be set to the same as legalName.
Representation of an account for payment purposes. Note that at least one of identification or proxy is expected to be present.
A code allocated to a financial or non-financial institution by the ISO 9362 Registration Authority as described in ISO 9362 Banking - Banking telecommunication messages - Business identifier code (BIC)
An organisation identified by a code allocated to a party as described in ISO 17442 Financial Services - Legal Entity Identifier (LEI).
Name by which an institution is known and which is usually used to identify that institution
Unique identification of the mandate, as assigned by the creditor. This field is used strictly by the Creditor for their own internal referencing and may be used to link collections to their related mandate. This is required for mandate initiations and cancellations.
Reference assigned to the mandate by the mandate management application. This is distinct from mandateIdentification (creditor's ID) and ZaMandatePaymentSchemeSupplementaryData.debtorBankMandateReference (debtor bank's reference).
Unique identification of the mandate request, as assigned by the creditor to the debtor when the underlying contract is concluded between the two parties. This field represents the Contract Reference Number. It appears on the debtor's bank statement to help them identify the deductions. This is required for mandate initiations and mandate cancellations.
Defines the frequency and duration of mandate collections.
Specifies the reason for a mandate action (amendment, cancellation, rejection).
Provides information to identify the underlying documents associated with the mandate
Indicates whether the mandate permits tracking for future collection instructions. Its exact meaning and relevance depend strictly on the mandate-management operation being performed:
1. Mandate Initiation & Amendment Requests
true) or revoked (false) for future collections against this mandate.2. Mandate Cancellation Requests
true: Instructs the clearing house to immediately cancel any active tracking records currently in the tracking queue for this mandate.false: Instructs the clearing house NOT to cancel records in tracking, allowing them to finish their tracking cycle despite the mandate being cancelled.3. Mandate Acceptance Reports
true or false) that was successfully saved to the Debtor Bank's Mandate Register.4. Mandate Suspensions & Information Requests
Provides details on the type of mandate.
This model is the basic representation of a Party. It is expanded on depending on whether the party is a person or an organisation.
Provides details about the reason for a mandate amendment.
Field Usage Guidelines: reason: For South African Mandate Schemes the reason for the amendment is specified as one of the below PROPRIETARY values:
MD02 - Reason has not been specified by end consumer.MD16 - Requested by Customer..MD17 - Amendment requested by Initiating Party.MD19 - Unsuspend a Mandate with changes.MD20 - Unsuspend an unchanged Mandate.MD21 - Amendment with no changes to Mandate Information.MD22 - Amendment with changes to Mandate Information.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 - MaximumDirectDebitTransactionAmountExceededReference to an original mandate. The partner may identify the mandate using any of the following identifiers, depending on the context of the request and the information available. At least one of originalMandateIdentification for the original mandate, or originalMandate must be provided.
For mandate amendment, cancellation and suspension requests, originalMandate is required and the originalMandateIdentification cannot be used as the sole reference.
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": "MandateAmendmentRequest", "underlyingAmendmentDetails": { "amendedMandate": { … }, "amendmentReason": { … }, "originalMandate": { … }, "originalMessageInformation": { … } } }