Electrum Regulated Payments API (26.0.0)

The Electrum Regulated Payments API is an asynchronous API that allows partners to participate in various nationally regulated payment schemes.

This document describes the operations exposed by Electrum for partners to consume in order to initiate outbound or respond to inbound payments.

As the Regulated Payments API is asynchronous, partners have a choice of how to integrate with Electrum:

Webhooks: Electrum will send events to the partner containing inbound payments to action, or responses to outbound payment requests. Webhooks are defined in this document.
Partner API: Electrum will call operations exposed by the partner containing inbound payments to action, or responses to outbound payment requests. The operations are defined in the Electrum Regulated Payments Partner API.

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. Partners may request the method of communication Electrum should use when selecting which payment schemes to participate in.

Download OpenAPI description

elpapi-redoc.json

elpapi-redoc.yaml

Overview

URL

https://electrum.co.za

Electrum Support

support@electrum.co.za

License

proprietary

Servers

Payments API sandbox

https://example.com/path/payments/api/v1/

transactional

Operations that participate in transaction processing, which may or may not have financial impact.

Operations

financial

Operations that participate in transaction processing and have financial impact.

Operations

credit-transfer

Operations related to credit transfer transactions.

Operations

direct-debit

Operations related to direct debit transactions.

Operations

payment-return

Operations related to payment returns.

Operations

account-management

Operations that involve customer account information.

Operations

proxy

Operations that involve the management or processing of proxies

Operations

scheme-inquiry

Operations that are related to retrieving information from industry for a particular scheme.

Operations

identifier-determination

Operations used to retrieve additional information related to an identifier

Operations

identifier-verification

Operations used to verify information relating to an account identifier

Operations

request-to-pay

Operations which pertain to a request for payment from a creditor to a debtor

Operations

funds-management

Operations related to the management of funds, including reservations, postings, and voiding of reservations.

Operations

refund

Operations related to the refund of a prior successful financial transaction.

Operations

risk-assessment

Operations related to the assessment and identification of risk in transactions.

Operations

fraud-assessment

Operations related to the processing of fraud assessments for payment transactions.

Operations

mandate-management

Operations related to the lifecycle management of direct debit mandates.

Operations

Initiate a new mandate request

Request

This operation is asynchronous. The outcome is delivered via the outboundMandateAcceptanceReport operation.

Instructs Electrum to send a mandate initiation request to the debtor's bank to establish a new direct debit mandate. The debtor bank will authenticate the mandate with the debtor and respond with an acceptance or rejection. The debtor and creditor may be at the same bank.

Scheme	Applicable
ZA_AC	✓

Headers

traceparentstring(traceparent)^[A-Fa-f0-9]{2}\-[A-Fa-f0-9]{32}\-[A-Fa-f0-9]...

A value used to trace an HTTP message within an Electrum Regulated Payments implementation. This field must be set as per the traceparent element defined in the W3C Trace Context Level 2 specification.

tracestatestring(tracestate)^[A-Za-z0-9=, _\*/@]{0,1024}$

A value used to provide context to an HTTP message as it is traced within an Electrum Regulated Payments implementation. This field must be set as per the tracestate element defined in the W3C Trace Context Level 2 specification.

Bodyapplication/jsonrequired

messageIdentifiersobject(MessageIdentifiers)required

Holds a point-to-point unique message identification string as well as a message's creation date time.

messageIdentifiers.creationDateTimestring(date-time)required

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

messageIdentifiers.messageIdentificationstring<= 35 charactersrequired

A reference used to unambiguously identify the message between the sending and receiving party. Take note that this uniquely identifies a single message in a potentially multi-message exchange to complete a payment.

supplementaryDataobject(SupplementaryData)

A list of key-value pairs to support adding any supplementary/additional data to an Electrum Regulated Payments API message.

initiatingPartyobject(Party)

This model is the basic representation of a Party. It is expanded on depending on whether the party is a person or an organisation.

instructedAgentobject(InstitutionIdentification)

instructingAgentobject(InstitutionIdentification)

mandateobject(Mandate)required

Core mandate data structure containing all the details of a direct debit mandate.

mandate.adjustmentobject(MandateAdjustmentRules)

Defines adjustment rules for mandate amounts.

mandate.authenticationobject(MandateAuthentication)

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

mandate.collectionAmountobject(Amount)

mandate.creditorobject(Party)required

This model is the basic representation of a Party. It is expanded on depending on whether the party is a person or an organisation.

mandate.creditor.addressobject(PostalAddress)

mandate.creditor.contactDetailsobject(ContactDetails)

mandate.creditor.countryOfResidencestring(CountryCode)[A-Z]{2,2}

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).

mandate.creditor.identificationobject(PartyIdentification)

The identification of a party, either a person or an organisation.

mandate.creditor.knownAsNamestring[ 1 .. 140 ] characters

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.

mandate.creditor.legalNamestring[ 1 .. 140 ] characters

The legal name by which this party is known (the "FICA" name). This is the full name of the party as found on country-issued documentation (national identity, company registration documentation etc).

mandate.creditorAccountobject(PaymentAccount)

Representation of an account for payment purposes. Note that at least one of identification or proxy is expected to be present.

mandate.creditorAgentobject(InstitutionIdentification)

mandate.creditorSchemeIdentificationobject(Party)

This model is the basic representation of a Party. It is expanded on depending on whether the party is a person or an organisation.

mandate.debtorobject(Party)required

This model is the basic representation of a Party. It is expanded on depending on whether the party is a person or an organisation.

mandate.debtor.addressobject(PostalAddress)

mandate.debtor.contactDetailsobject(ContactDetails)

mandate.debtor.countryOfResidencestring(CountryCode)[A-Z]{2,2}

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).

mandate.debtor.identificationobject(PartyIdentification)

The identification of a party, either a person or an organisation.

mandate.debtor.knownAsNamestring[ 1 .. 140 ] characters

mandate.debtor.legalNamestring[ 1 .. 140 ] characters

The legal name by which this party is known (the "FICA" name). This is the full name of the party as found on country-issued documentation (national identity, company registration documentation etc).

mandate.debtorAccountobject(PaymentAccount)

Representation of an account for payment purposes. Note that at least one of identification or proxy is expected to be present.

mandate.debtorAgentobject(InstitutionIdentification)required

mandate.debtorAgent.additionalIdentificationsArray of objects(AccountIdentification)

mandate.debtorAgent.addressobject(PostalAddress)

mandate.debtorAgent.bicfistring^[A-Z0-9]{4,4}[A-Z]{2,2}[A-Z0-9]{2,2}([A-Z0-9...

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)

mandate.debtorAgent.branchobject(BranchIdentification)

mandate.debtorAgent.clearingSystemMemberIdobject(ClearingSystemMemberIdentification)

mandate.debtorAgent.leistring[A-Z0-9]{18,18}[0-9]{2,2}

An organisation identified by a code allocated to a party as described in ISO 17442 Financial Services - Legal Entity Identifier (LEI).

mandate.debtorAgent.namestring<= 140 characters

Name by which an institution is known and which is usually used to identify that institution

mandate.debtorAgent.companyRegistrationstring<= 35 charactersDeprecated

A unique identifier assigned to a company or organisation by a duly appointed authority within a country.

mandate.debtorAgent.memberIdstring<= 35 charactersDeprecated

Deprecated. Please use the preferred clearingSystemMemberId.memberId instead. Identification of a member of a clearing system.

mandate.firstCollectionAmountobject(Amount)

mandate.mandateIdentificationstring<= 35 characters

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.

mandate.mandateReferencestring<= 35 characters

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).

mandate.mandateRequestIdentificationstring<= 35 characters

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.

mandate.maximumAmountobject(Amount)

mandate.occurrencesobject(MandateOccurrences)

Defines the frequency and duration of mandate collections.

mandate.reasonobject(MandateReason)

Specifies the reason for a mandate action (amendment, cancellation, rejection).

mandate.referredDocumentArray of objects(ReferredDocument)

Provides information to identify the underlying documents associated with the mandate

mandate.trackingIndicatorboolean

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

Required: Specifies whether tracking capabilities are permitted (true) or revoked (false) for future collections against this mandate.

2. Mandate Cancellation Requests

Required: Acts specifically as a Tracking Cancellation Indicator to manage collections that are already in-flight.
- 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

Required: Echoes the definitive tracking setting (true or false) that was successfully saved to the Debtor Bank's Mandate Register.

4. Mandate Suspensions & Information Requests

Not Applicable: This field is ignored for lookup and suspension operations.

mandate.typeobject(MandateTypeInformation)

Provides details on the type of mandate.

mandate.ultimateCreditorobject(Party)

This model is the basic representation of a Party. It is expanded on depending on whether the party is a person or an organisation.

mandate.ultimateDebtorobject(Party)

This model is the basic representation of a Party. It is expanded on depending on whether the party is a person or an organisation.

paymentSchemeobject(MandatePaymentScheme)required

Designates which scheme a mandate operation is associated with and describes scheme-specific information for the mandate operation where relevant.

paymentScheme.schemastring(PaymentSchemeName)required

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.

Enum"ZA_RTC""ZA_RPP""ZA_EFT""ZA_AC""ZA_RMS""CBPR_PLUS"

Discriminator

paymentScheme.schemeDataobject(ZaAcMandatePaymentSchemeData)required

South Africa specific supplementary data fields. These fields supplement the core mandate structure with local requirements.

paymentScheme.schemeData.authenticationTypestringrequired

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).

Enum"REAL_TIME""PREAUTH""BATCH""NOT_APPLICABLE"

paymentScheme.schemeData.collectionDayinteger[ 1 .. 99 ]

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.

paymentScheme.schemeData.debitValueTypestring

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.

Enum"FIXED""VARIABLE""USAGE_BASED"

paymentScheme.schemeData.debtorBankMandateReferencestring<= 22 characters^[0-9]{4}20[0-9]{2}[0-1][0-9][0-3][0-9].{10}$...

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):

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.

paymentScheme.schemeData.mandateRequestTransactionIdentifierstring(MandateRequestTransactionIdentifier)<= 35 characters^\d{4}\d{4}-\d{2}-\d{2}\d{9}$

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 provided MRTI is used by Electrum.
If Electrum is the source of truth for mandate state the 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):

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 MRTI for the initiation request. If not provided by the client, Electrum generates one automatically.
Mandate Amendment Request: A new, unique 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).
Mandate Cancellation Request:
- In-flight cancellation: If cancelling a mandate request that is still in-flight (e.g. awaiting debtor authentication), the 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.
- Active mandate cancellation: If the mandate is already fully registered and active, a new, unique MRTI must be issued for the cancellation request. If not provided, Electrum determines the mandate state and applies the correct rule automatically.
Mandate Acceptance Report: The response echoes back the MRTI from the request being responded to. For API-level correlation, clients use originalMessageIdentifiers.messageIdentification instead.
Mandate Status Report: The status report echoes back the MRTI from the request being reported on. For API-level correlation, clients use originalMessageIdentifiers.messageIdentification instead.

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.

paymentScheme.schemeData.requestTransmissionNumberinteger(MandatePaymentSchemeRequestTransmissionNumber)[ 1 .. 4 ]

Sequence number for the message's transmission. Used exclusively for real-time (TT1/TT3) messages to track message retries. 1 = original message transmission, 2-4 = retries.

schemastringrequired

Value"MandateInitiationRequest"

curl -i -X POST \
  https://example.com/path/payments/api/v1/mandates/outbound/initiation \
  -H 'Content-Type: application/json' \
  -H 'traceparent: string' \
  -H 'tracestate: string' \
  -d '{
    "schema": "MandateInitiationRequest",
    "messageIdentifiers": {
      "messageIdentification": "100/MANOT/00210007/20190305/000511",
      "creationDateTime": "2019-03-05T10:04:44Z"
    },
    "paymentScheme": {
      "schema": "ZA_AC",
      "schemeData": {
        "mandateRequestTransactionIdentifier": "00072019-03-05000000086",
        "authenticationType": "REAL_TIME",
        "requestTransmissionNumber": 1,
        "collectionDay": 29,
        "debitValueType": "VARIABLE"
      }
    },
    "initiatingParty": {
      "legalName": "EXAMPLE LOANS"
    },
    "mandate": {
      "mandateIdentification": "2710317",
      "mandateRequestIdentification": "2710317004",
      "trackingIndicator": true,
      "type": {
        "localInstrument": {
          "schema": "PROPRIETARY",
          "value": "0227"
        }
      },
      "occurrences": {
        "sequenceType": "RCUR",
        "frequency": {
          "schema": "MonthlyFrequency",
          "dayOfMonth": 15
        },
        "validFrom": "2019-03-05",
        "firstCollectionDate": "2019-03-29"
      },
      "collectionAmount": {
        "value": 3443.83,
        "currency": "ZAR"
      },
      "maximumAmount": {
        "value": 5165.75,
        "currency": "ZAR"
      },
      "creditor": {
        "legalName": "Creditor Name",
        "identification": {
          "schema": "ORGANISATION",
          "identifiers": [
            {
              "schema": "BIC",
              "BIC": "RY8PEG0L"
            }
          ]
        }
      },
      "creditorAccount": {
        "identification": {
          "schema": "GENERIC",
          "scheme": {
            "schema": "PROPRIETARY",
            "value": "ACCOUNT_NUMBER"
          },
          "value": "10173412345"
        },
        "type": {
          "schema": "CODE",
          "value": "CACC"
        }
      },
      "creditorAgent": {
        "clearingSystemMemberId": {
          "memberId": "430000"
        }
      },
      "ultimateCreditor": {
        "legalName": "Ultimate Creditor"
      },
      "debtor": {
        "legalName": "Debtor Name",
        "identification": {
          "schema": "PERSON",
          "identifiers": [
            {
              "identification": "I/9905140859123",
              "scheme": {
                "schema": "CODE",
                "value": "NIDN"
              }
            }
          ]
        },
        "contactDetails": {
          "phoneNumber": "+27-112569000",
          "emailAddress": "support@debtor.com"
        }
      },
      "debtorAccount": {
        "identification": {
          "schema": "GENERIC",
          "scheme": {
            "schema": "PROPRIETARY",
            "value": "ACCOUNT_NUMBER"
          },
          "value": "10173412345"
        },
        "type": {
          "schema": "CODE",
          "value": "SVGS"
        }
      },
      "debtorAgent": {
        "clearingSystemMemberId": {
          "memberId": "470010"
        }
      },
      "ultimateDebtor": {
        "legalName": "Ultimate Debtor"
      }
    }
  }'

Responses

Accepted. RFC9110 - 202

Response

No content

Request an amendment to an existing mandate

Request

This operation is asynchronous. The outcome is delivered via the outboundMandateAcceptanceReport operation.

Instructs Electrum to send a mandate amendment request to the debtor's bank to modify the terms of an existing mandate. Depending on the type of amendment, the debtor may need to re-authenticate. The debtor bank will respond with an acceptance or rejection. The debtor and creditor may be at the same bank.

Scheme	Applicable
ZA_AC	✓

Headers

traceparentstring(traceparent)^[A-Fa-f0-9]{2}\-[A-Fa-f0-9]{32}\-[A-Fa-f0-9]...

tracestatestring(tracestate)^[A-Za-z0-9=, _\*/@]{0,1024}$

Bodyapplication/jsonrequired

messageIdentifiersobject(MessageIdentifiers)required

Holds a point-to-point unique message identification string as well as a message's creation date time.

messageIdentifiers.creationDateTimestring(date-time)required

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

messageIdentifiers.messageIdentificationstring<= 35 charactersrequired

supplementaryDataobject(SupplementaryData)

A list of key-value pairs to support adding any supplementary/additional data to an Electrum Regulated Payments API message.

initiatingPartyobject(Party)

This model is the basic representation of a Party. It is expanded on depending on whether the party is a person or an organisation.

instructedAgentobject(InstitutionIdentification)

instructingAgentobject(InstitutionIdentification)

paymentSchemeobject(MandatePaymentScheme)required

Designates which scheme a mandate operation is associated with and describes scheme-specific information for the mandate operation where relevant.

paymentScheme.schemastring(PaymentSchemeName)required

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.

Enum"ZA_RTC""ZA_RPP""ZA_EFT""ZA_AC""ZA_RMS""CBPR_PLUS"

Discriminator

paymentScheme.schemeDataobject(ZaAcMandatePaymentSchemeData)required

South Africa specific supplementary data fields. These fields supplement the core mandate structure with local requirements.

paymentScheme.schemeData.authenticationTypestringrequired

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).

Enum"REAL_TIME""PREAUTH""BATCH""NOT_APPLICABLE"

paymentScheme.schemeData.collectionDayinteger[ 1 .. 99 ]

The Payer's preferred recurring day for collection from their bank account.

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).

Note: According to clearing rules, Debtor Banks are only required to enforce this strict date validation on Weekly and Monthly frequencies.

paymentScheme.schemeData.debitValueTypestring

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.

Enum"FIXED""VARIABLE""USAGE_BASED"

paymentScheme.schemeData.debtorBankMandateReferencestring<= 22 characters^[0-9]{4}20[0-9]{2}[0-1][0-9][0-3][0-9].{10}$...

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):

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.

paymentScheme.schemeData.mandateRequestTransactionIdentifierstring(MandateRequestTransactionIdentifier)<= 35 characters^\d{4}\d{4}-\d{2}-\d{2}\d{9}$

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 provided MRTI is used by Electrum.
If Electrum is the source of truth for mandate state the 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):

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 MRTI for the initiation request. If not provided by the client, Electrum generates one automatically.
Mandate Amendment Request: A new, unique 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).
Mandate Cancellation Request:
- In-flight cancellation: If cancelling a mandate request that is still in-flight (e.g. awaiting debtor authentication), the 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.
- Active mandate cancellation: If the mandate is already fully registered and active, a new, unique MRTI must be issued for the cancellation request. If not provided, Electrum determines the mandate state and applies the correct rule automatically.
Mandate Acceptance Report: The response echoes back the MRTI from the request being responded to. For API-level correlation, clients use originalMessageIdentifiers.messageIdentification instead.
Mandate Status Report: The status report echoes back the MRTI from the request being reported on. For API-level correlation, clients use originalMessageIdentifiers.messageIdentification instead.

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.

paymentScheme.schemeData.requestTransmissionNumberinteger(MandatePaymentSchemeRequestTransmissionNumber)[ 1 .. 4 ]

Sequence number for the message's transmission. Used exclusively for real-time (TT1/TT3) messages to track message retries. 1 = original message transmission, 2-4 = retries.

schemastringrequired

Value"MandateAmendmentRequest"

underlyingAmendmentDetailsobject(UnderlyingAmendmentDetails)required

Contains the details of the mandate amendment including the reason, amended mandate, and original mandate reference.

underlyingAmendmentDetails.amendedMandateobject(Mandate)required

Core mandate data structure containing all the details of a direct debit mandate.

underlyingAmendmentDetails.amendedMandate.adjustmentobject(MandateAdjustmentRules)

Defines adjustment rules for mandate amounts.

underlyingAmendmentDetails.amendedMandate.authenticationobject(MandateAuthentication)

underlyingAmendmentDetails.amendedMandate.collectionAmountobject(Amount)

underlyingAmendmentDetails.amendedMandate.creditorobject(Party)required

This model is the basic representation of a Party. It is expanded on depending on whether the party is a person or an organisation.

underlyingAmendmentDetails.amendedMandate.creditor.addressobject(PostalAddress)

underlyingAmendmentDetails.amendedMandate.creditor.contactDetailsobject(ContactDetails)

underlyingAmendmentDetails.amendedMandate.creditor.countryOfResidencestring(CountryCode)[A-Z]{2,2}

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).

underlyingAmendmentDetails.amendedMandate.creditor.identificationobject(PartyIdentification)

The identification of a party, either a person or an organisation.

underlyingAmendmentDetails.amendedMandate.creditor.knownAsNamestring[ 1 .. 140 ] characters

underlyingAmendmentDetails.amendedMandate.creditor.legalNamestring[ 1 .. 140 ] characters

The legal name by which this party is known (the "FICA" name). This is the full name of the party as found on country-issued documentation (national identity, company registration documentation etc).

underlyingAmendmentDetails.amendedMandate.creditorAccountobject(PaymentAccount)

Representation of an account for payment purposes. Note that at least one of identification or proxy is expected to be present.

underlyingAmendmentDetails.amendedMandate.creditorAgentobject(InstitutionIdentification)

underlyingAmendmentDetails.amendedMandate.creditorSchemeIdentificationobject(Party)

This model is the basic representation of a Party. It is expanded on depending on whether the party is a person or an organisation.

underlyingAmendmentDetails.amendedMandate.debtorobject(Party)required

This model is the basic representation of a Party. It is expanded on depending on whether the party is a person or an organisation.

underlyingAmendmentDetails.amendedMandate.debtor.addressobject(PostalAddress)

underlyingAmendmentDetails.amendedMandate.debtor.contactDetailsobject(ContactDetails)

underlyingAmendmentDetails.amendedMandate.debtor.countryOfResidencestring(CountryCode)[A-Z]{2,2}

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).

underlyingAmendmentDetails.amendedMandate.debtor.identificationobject(PartyIdentification)

The identification of a party, either a person or an organisation.

underlyingAmendmentDetails.amendedMandate.debtor.knownAsNamestring[ 1 .. 140 ] characters

underlyingAmendmentDetails.amendedMandate.debtor.legalNamestring[ 1 .. 140 ] characters

The legal name by which this party is known (the "FICA" name). This is the full name of the party as found on country-issued documentation (national identity, company registration documentation etc).

underlyingAmendmentDetails.amendedMandate.debtorAccountobject(PaymentAccount)

Representation of an account for payment purposes. Note that at least one of identification or proxy is expected to be present.

underlyingAmendmentDetails.amendedMandate.debtorAgentobject(InstitutionIdentification)required

underlyingAmendmentDetails.amendedMandate.debtorAgent.additionalIdentificationsArray of objects(AccountIdentification)

underlyingAmendmentDetails.amendedMandate.debtorAgent.addressobject(PostalAddress)

underlyingAmendmentDetails.amendedMandate.debtorAgent.bicfistring^[A-Z0-9]{4,4}[A-Z]{2,2}[A-Z0-9]{2,2}([A-Z0-9...

underlyingAmendmentDetails.amendedMandate.debtorAgent.branchobject(BranchIdentification)

underlyingAmendmentDetails.amendedMandate.debtorAgent.clearingSystemMemberIdobject(ClearingSystemMemberIdentification)

underlyingAmendmentDetails.amendedMandate.debtorAgent.leistring[A-Z0-9]{18,18}[0-9]{2,2}

An organisation identified by a code allocated to a party as described in ISO 17442 Financial Services - Legal Entity Identifier (LEI).

underlyingAmendmentDetails.amendedMandate.debtorAgent.namestring<= 140 characters

Name by which an institution is known and which is usually used to identify that institution

underlyingAmendmentDetails.amendedMandate.debtorAgent.companyRegistrationstring<= 35 charactersDeprecated

A unique identifier assigned to a company or organisation by a duly appointed authority within a country.

underlyingAmendmentDetails.amendedMandate.debtorAgent.memberIdstring<= 35 charactersDeprecated

Deprecated. Please use the preferred clearingSystemMemberId.memberId instead. Identification of a member of a clearing system.

underlyingAmendmentDetails.amendedMandate.firstCollectionAmountobject(Amount)

underlyingAmendmentDetails.amendedMandate.mandateIdentificationstring<= 35 characters

underlyingAmendmentDetails.amendedMandate.mandateReferencestring<= 35 characters

underlyingAmendmentDetails.amendedMandate.mandateRequestIdentificationstring<= 35 characters

underlyingAmendmentDetails.amendedMandate.maximumAmountobject(Amount)

underlyingAmendmentDetails.amendedMandate.occurrencesobject(MandateOccurrences)

Defines the frequency and duration of mandate collections.

underlyingAmendmentDetails.amendedMandate.reasonobject(MandateReason)

Specifies the reason for a mandate action (amendment, cancellation, rejection).

underlyingAmendmentDetails.amendedMandate.referredDocumentArray of objects(ReferredDocument)

Provides information to identify the underlying documents associated with the mandate

underlyingAmendmentDetails.amendedMandate.trackingIndicatorboolean

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

Required: Specifies whether tracking capabilities are permitted (true) or revoked (false) for future collections against this mandate.

2. Mandate Cancellation Requests

Required: Acts specifically as a Tracking Cancellation Indicator to manage collections that are already in-flight.
- 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

Required: Echoes the definitive tracking setting (true or false) that was successfully saved to the Debtor Bank's Mandate Register.

4. Mandate Suspensions & Information Requests

Not Applicable: This field is ignored for lookup and suspension operations.

underlyingAmendmentDetails.amendedMandate.typeobject(MandateTypeInformation)

Provides details on the type of mandate.

underlyingAmendmentDetails.amendedMandate.ultimateCreditorobject(Party)

This model is the basic representation of a Party. It is expanded on depending on whether the party is a person or an organisation.

underlyingAmendmentDetails.amendedMandate.ultimateDebtorobject(Party)

This model is the basic representation of a Party. It is expanded on depending on whether the party is a person or an organisation.

underlyingAmendmentDetails.amendmentReasonobject(MandateAmendmentReason)required

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.

underlyingAmendmentDetails.amendmentReason.additionalInformationArray of strings

underlyingAmendmentDetails.amendmentReason.originatorobject(Party)

This model is the basic representation of a Party. It is expanded on depending on whether the party is a person or an organisation.

underlyingAmendmentDetails.amendmentReason.reasonobject(MandateReason)required

Specifies the reason for a mandate action (amendment, cancellation, rejection).

underlyingAmendmentDetails.amendmentReason.reason.schemastringrequired

Identifies the value as being a pre-defined code. Always CODE.

Discriminator

underlyingAmendmentDetails.amendmentReason.reason.valuestringrequired

AC01 - IncorrectAccountNumber
AC04 - ClosedAccountNumber
AC06 - BlockedAccount
AG01 - TransactionForbidden
AG02 - InvalidBankOperationCode
AM02 - NotAllowedAmount
AM03 - NotAllowedCurrency
AM05 - Duplication
BE01 - InconsistenWithEndCustomer
BE04 - MissingCreditorAddress
BE05 - UnrecognisedInitiatingParty
BE06 - UnknownEndCustomer
BE07 - MissingDebtorAddress
DT01 - InvalidDate
FF01 - InvalidFileFormat
MD01 - NoMandate
MD02 - MissingMandatoryInformationInMandate
MD07 - EndCustomerDeceased
MD08 - NoMandateServiceByAgent
MD09 - NoMandateServiceOnCustomer
MD10 - NoMandateServiceForSpecified
MD11 - UnrecognisedAgent
MD12 - NotUniqueMandateReference
MD13 - IncorrectCustomerAuthentication
MD14 - IncorrectAgent
MD15 - IncorrectCurrency
MD16 - RequestedByCustomer
MD17 - RequestedByInitiatingParty
MD18 - RequestedByInitiatingPartyAndCustomer
MD19 - MandateCancelledDueToEarlySettlement
MD20 - MandateExpired
MD21 - MandateCancelledDueToFraud
MD22 - MandateInitiationCancelled
MD23 - MandateAmendmentCancelled
MS02 - NotSpecifiedReasonCustomerGenerated
MS03 - NotSpecifiedReasonAgentGenerated
NARR - Narrative
RC01 - BankIdentifierIncorrect
RF01 - NotUniqueTransactionReference
RR01 - MissingDebtorAccountOrIdentification
RR02 - MissingDebtorNameOrAddress
RR03 - MissingCreditorNameOrAddress
RR04 - RegulatoryReason
SL01 - SpecificServiceOfferedByDebtorAgent
SL11 - CreditorNotOnWhitelistOfDebtor
SL12 - CreditorOnBlacklistOfDebtor
SL13 - MaximumNumberOfDirectDebitTransactionsExceeded
SL14 - MaximumDirectDebitTransactionAmountExceeded

Enum"AC01""AC04""AC06""AG01""AG02""AM02""AM03""AM05""BE01""BE04"

underlyingAmendmentDetails.originalMandateobject(OriginalMandateReference)required

Reference 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.

underlyingAmendmentDetails.originalMandate.originalMandateobject(Mandate)

Core mandate data structure containing all the details of a direct debit mandate.

underlyingAmendmentDetails.originalMandate.originalMandateIdentificationstring<= 35 characters

Unique identification to unambiguously identify the original mandate. Can be the mandateIdentification as assigned by the creditor or the mandate reference number as assigned by the debtor agent

underlyingAmendmentDetails.originalMessageInformationobject(OriginalMandateMessageInformation)

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.

curl -i -X POST \
  https://example.com/path/payments/api/v1/mandates/outbound/amendment \
  -H 'Content-Type: application/json' \
  -H 'traceparent: string' \
  -H 'tracestate: string' \
  -d '{
    "schema": "MandateAmendmentRequest",
    "paymentScheme": {
      "schema": "ZA_AC",
      "schemeData": {
        "mandateRequestTransactionIdentifier": "00072019-03-05000000086",
        "authenticationType": "REAL_TIME",
        "requestTransmissionNumber": 1,
        "collectionDay": 99,
        "debitValueType": "USAGE_BASED",
        "debtorBankMandateReference": "0003202501015177310122"
      }
    },
    "messageIdentifiers": {
      "messageIdentification": "100/MANOM/00210007/20190502/000040",
      "creationDateTime": "2019-05-02T15:43:47Z"
    },
    "initiatingParty": {
      "legalName": "EXAMPLE LOANS"
    },
    "underlyingAmendmentDetails": {
      "amendmentReason": {
        "reason": {
          "schema": "PROPRIETARY",
          "value": "MD16"
        },
        "additionalInformation": [
          "Mandate amendment requested by creditor due to contract changes"
        ]
      },
      "amendedMandate": {
        "mandateIdentification": "6858841",
        "mandateRequestIdentification": "6858841001",
        "trackingIndicator": true,
        "type": {
          "localInstrument": {
            "schema": "PROPRIETARY",
            "value": "0227"
          }
        },
        "occurrences": {
          "sequenceType": "RCUR",
          "frequency": {
            "schema": "MonthlyFrequency",
            "dayOfMonth": 15
          },
          "validFrom": "2019-04-26",
          "firstCollectionDate": "2019-04-30"
        },
        "collectionAmount": {
          "value": 3800,
          "currency": "ZAR"
        },
        "maximumAmount": {
          "value": 5500,
          "currency": "ZAR"
        },
        "creditor": {
          "legalName": "Creditor Name",
          "identification": {
            "schema": "ORGANISATION",
            "identifiers": [
              {
                "schema": "BIC",
                "BIC": "RY8PEG0L"
              }
            ]
          }
        },
        "creditorAccount": {
          "identification": {
            "schema": "GENERIC",
            "scheme": {
              "schema": "PROPRIETARY",
              "value": "ACCOUNT_NUMBER"
            },
            "value": "10173412345"
          },
          "type": {
            "schema": "CODE",
            "value": "CACC"
          }
        },
        "creditorAgent": {
          "clearingSystemMemberId": {
            "memberId": "430000"
          }
        },
        "debtor": {
          "legalName": "Debtor Name",
          "identification": {
            "schema": "PERSON",
            "identifiers": [
              {
                "identification": "I/5906140859123",
                "scheme": {
                  "schema": "CODE",
                  "value": "NIDN"
                }
              }
            ]
          }
        },
        "debtorAccount": {
          "identification": {
            "schema": "GENERIC",
            "scheme": {
              "schema": "PROPRIETARY",
              "value": "ACCOUNT_NUMBER"
            },
            "value": "10173412345"
          },
          "type": {
            "schema": "CODE",
            "value": "SVGS"
          }
        },
        "debtorAgent": {
          "clearingSystemMemberId": {
            "memberId": "990010"
          }
        },
        "ultimateDebtor": {
          "legalName": "Ultimate Debtor"
        }
      },
      "originalMandate": {
        "originalMandate": {
          "mandateIdentification": "2710317",
          "mandateRequestIdentification": "2710317004",
          "trackingIndicator": true,
          "creditor": {
            "legalName": "Creditor Name",
            "identification": {
              "schema": "ORGANISATION",
              "identifiers": [
                {
                  "schema": "BIC",
                  "BIC": "RY8PEG0L"
                }
              ]
            },
            "contactDetails": {
              "phoneNumber": "+27-112569000",
              "emailAddress": "support@creditor.com"
            }
          },
          "debtor": {
            "legalName": "Debtor Name",
            "identification": {
              "schema": "PERSON",
              "identifiers": [
                {
                  "identification": "I/9905140859123",
                  "scheme": {
                    "schema": "CODE",
                    "value": "NIDN"
                  }
                }
              ]
            },
            "contactDetails": {
              "phoneNumber": "+27-112569000",
              "emailAddress": "support@debtor.com"
            }
          },
          "debtorAgent": {
            "clearingSystemMemberId": {
              "memberId": "470010"
            }
          }
        }
      }
    }
  }'

Responses

Accepted. RFC9110 - 202

Response

No content

Request cancellation of an existing mandate

Request

This operation is asynchronous. The outcome is delivered via the outboundMandateAcceptanceReport operation.

Instructs Electrum to send a mandate cancellation request to the debtor's bank to terminate an existing mandate. The debtor and creditor may be at the same bank.

Scheme	Applicable
ZA_AC	✓

Headers

traceparentstring(traceparent)^[A-Fa-f0-9]{2}\-[A-Fa-f0-9]{32}\-[A-Fa-f0-9]...

tracestatestring(tracestate)^[A-Za-z0-9=, _\*/@]{0,1024}$

Bodyapplication/jsonrequired

messageIdentifiersobject(MessageIdentifiers)required

Holds a point-to-point unique message identification string as well as a message's creation date time.

messageIdentifiers.creationDateTimestring(date-time)required

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

messageIdentifiers.messageIdentificationstring<= 35 charactersrequired

supplementaryDataobject(SupplementaryData)

A list of key-value pairs to support adding any supplementary/additional data to an Electrum Regulated Payments API message.

initiatingPartyobject(Party)

This model is the basic representation of a Party. It is expanded on depending on whether the party is a person or an organisation.

instructedAgentobject(InstitutionIdentification)

instructingAgentobject(InstitutionIdentification)

paymentSchemeobject(MandatePaymentScheme)required

Designates which scheme a mandate operation is associated with and describes scheme-specific information for the mandate operation where relevant.

paymentScheme.schemastring(PaymentSchemeName)required

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.

Enum"ZA_RTC""ZA_RPP""ZA_EFT""ZA_AC""ZA_RMS""CBPR_PLUS"

Discriminator

paymentScheme.schemeDataobject(ZaAcMandatePaymentSchemeData)required

South Africa specific supplementary data fields. These fields supplement the core mandate structure with local requirements.

paymentScheme.schemeData.authenticationTypestringrequired

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).

Enum"REAL_TIME""PREAUTH""BATCH""NOT_APPLICABLE"

paymentScheme.schemeData.collectionDayinteger[ 1 .. 99 ]

The Payer's preferred recurring day for collection from their bank account.

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).

Note: According to clearing rules, Debtor Banks are only required to enforce this strict date validation on Weekly and Monthly frequencies.

paymentScheme.schemeData.debitValueTypestring

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.

Enum"FIXED""VARIABLE""USAGE_BASED"

paymentScheme.schemeData.debtorBankMandateReferencestring<= 22 characters^[0-9]{4}20[0-9]{2}[0-1][0-9][0-3][0-9].{10}$...

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):

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.

paymentScheme.schemeData.mandateRequestTransactionIdentifierstring(MandateRequestTransactionIdentifier)<= 35 characters^\d{4}\d{4}-\d{2}-\d{2}\d{9}$

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 provided MRTI is used by Electrum.
If Electrum is the source of truth for mandate state the 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):

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 MRTI for the initiation request. If not provided by the client, Electrum generates one automatically.
Mandate Amendment Request: A new, unique 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).
Mandate Cancellation Request:
- In-flight cancellation: If cancelling a mandate request that is still in-flight (e.g. awaiting debtor authentication), the 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.
- Active mandate cancellation: If the mandate is already fully registered and active, a new, unique MRTI must be issued for the cancellation request. If not provided, Electrum determines the mandate state and applies the correct rule automatically.
Mandate Acceptance Report: The response echoes back the MRTI from the request being responded to. For API-level correlation, clients use originalMessageIdentifiers.messageIdentification instead.
Mandate Status Report: The status report echoes back the MRTI from the request being reported on. For API-level correlation, clients use originalMessageIdentifiers.messageIdentification instead.

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.

paymentScheme.schemeData.requestTransmissionNumberinteger(MandatePaymentSchemeRequestTransmissionNumber)[ 1 .. 4 ]

Sequence number for the message's transmission. Used exclusively for real-time (TT1/TT3) messages to track message retries. 1 = original message transmission, 2-4 = retries.

schemastringrequired

Value"MandateCancellationRequest"

underlyingCancellationDetailsobject(UnderlyingCancellationDetails)required

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.

underlyingCancellationDetails.cancellationReasonobject(MandateCancellationReason)required

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.

underlyingCancellationDetails.cancellationReason.additionalInformationArray of strings

underlyingCancellationDetails.cancellationReason.originatorobject(Party)

This model is the basic representation of a Party. It is expanded on depending on whether the party is a person or an organisation.

underlyingCancellationDetails.cancellationReason.reasonobject(MandateReason)required

Specifies the reason for a mandate action (amendment, cancellation, rejection).

underlyingCancellationDetails.cancellationReason.reason.schemastringrequired

Identifies the value as being a pre-defined code. Always CODE.

Discriminator

underlyingCancellationDetails.cancellationReason.reason.valuestringrequired

AC01 - IncorrectAccountNumber
AC04 - ClosedAccountNumber
AC06 - BlockedAccount
AG01 - TransactionForbidden
AG02 - InvalidBankOperationCode
AM02 - NotAllowedAmount
AM03 - NotAllowedCurrency
AM05 - Duplication
BE01 - InconsistenWithEndCustomer
BE04 - MissingCreditorAddress
BE05 - UnrecognisedInitiatingParty
BE06 - UnknownEndCustomer
BE07 - MissingDebtorAddress
DT01 - InvalidDate
FF01 - InvalidFileFormat
MD01 - NoMandate
MD02 - MissingMandatoryInformationInMandate
MD07 - EndCustomerDeceased
MD08 - NoMandateServiceByAgent
MD09 - NoMandateServiceOnCustomer
MD10 - NoMandateServiceForSpecified
MD11 - UnrecognisedAgent
MD12 - NotUniqueMandateReference
MD13 - IncorrectCustomerAuthentication
MD14 - IncorrectAgent
MD15 - IncorrectCurrency
MD16 - RequestedByCustomer
MD17 - RequestedByInitiatingParty
MD18 - RequestedByInitiatingPartyAndCustomer
MD19 - MandateCancelledDueToEarlySettlement
MD20 - MandateExpired
MD21 - MandateCancelledDueToFraud
MD22 - MandateInitiationCancelled
MD23 - MandateAmendmentCancelled
MS02 - NotSpecifiedReasonCustomerGenerated
MS03 - NotSpecifiedReasonAgentGenerated
NARR - Narrative
RC01 - BankIdentifierIncorrect
RF01 - NotUniqueTransactionReference
RR01 - MissingDebtorAccountOrIdentification
RR02 - MissingDebtorNameOrAddress
RR03 - MissingCreditorNameOrAddress
RR04 - RegulatoryReason
SL01 - SpecificServiceOfferedByDebtorAgent
SL11 - CreditorNotOnWhitelistOfDebtor
SL12 - CreditorOnBlacklistOfDebtor
SL13 - MaximumNumberOfDirectDebitTransactionsExceeded
SL14 - MaximumDirectDebitTransactionAmountExceeded

Enum"AC01""AC04""AC06""AG01""AG02""AM02""AM03""AM05""BE01""BE04"

underlyingCancellationDetails.originalMandateobject(OriginalMandateReference)required

For mandate amendment, cancellation and suspension requests, originalMandate is required and the originalMandateIdentification cannot be used as the sole reference.

underlyingCancellationDetails.originalMandate.originalMandateobject(Mandate)

Core mandate data structure containing all the details of a direct debit mandate.

underlyingCancellationDetails.originalMandate.originalMandateIdentificationstring<= 35 characters

Unique identification to unambiguously identify the original mandate. Can be the mandateIdentification as assigned by the creditor or the mandate reference number as assigned by the debtor agent

underlyingCancellationDetails.originalMessageInformationobject(OriginalMandateMessageInformation)

curl -i -X POST \
  https://example.com/path/payments/api/v1/mandates/outbound/cancellation \
  -H 'Content-Type: application/json' \
  -H 'traceparent: string' \
  -H 'tracestate: string' \
  -d '{
    "schema": "MandateCancellationRequest",
    "paymentScheme": {
      "schema": "ZA_AC",
      "schemeData": {
        "mandateRequestTransactionIdentifier": "00072019-03-05000000086",
        "authenticationType": "REAL_TIME",
        "requestTransmissionNumber": 1,
        "collectionDay": 99,
        "debitValueType": "USAGE_BASED"
      }
    },
    "messageIdentifiers": {
      "messageIdentification": "100/MANCO/00999003/20240305/000001",
      "creationDateTime": "2024-03-05T10:08:01Z"
    },
    "initiatingParty": {
      "legalName": "EXAMPLE LOANS"
    },
    "instructingAgent": {
      "clearingSystemMemberId": {
        "memberId": "999003"
      }
    },
    "instructedAgent": {
      "clearingSystemMemberId": {
        "memberId": "999002"
      }
    },
    "underlyingCancellationDetails": {
      "originalMessageInformation": {
        "messageIdentification": "100/MANAM/00210007/20190305/000511",
        "creationDateTime": "2019-03-05T10:04:44Z",
        "messageNameIdentification": "MandateAmendmentRequest"
      },
      "cancellationReason": {
        "reason": {
          "schema": "PROPRIETARY",
          "value": "MICN"
        },
        "additionalInformation": [
          "Mandate cancellation requested by creditor"
        ]
      },
      "originalMandate": {
        "originalMandate": {
          "mandateIdentification": "33005",
          "mandateRequestIdentification": "CR000000029853",
          "trackingIndicator": true,
          "type": {
            "localInstrument": {
              "schema": "PROPRIETARY",
              "value": "0227"
            }
          },
          "occurrences": {
            "sequenceType": "RCUR",
            "frequency": {
              "schema": "MonthlyFrequency",
              "dayOfMonth": 15
            },
            "validFrom": "2019-04-26",
            "firstCollectionDate": "2019-04-30"
          },
          "creditor": {
            "legalName": "Creditor Name",
            "identification": {
              "schema": "ORGANISATION",
              "identifiers": [
                {
                  "schema": "BIC",
                  "BIC": "RY8PEG0L"
                }
              ]
            },
            "contactDetails": {
              "phoneNumber": "+27-86-0001234",
              "emailAddress": "collections@exampleloans.example.co.za"
            }
          },
          "creditorAccount": {
            "identification": {
              "schema": "GENERIC",
              "scheme": {
                "schema": "PROPRIETARY",
                "value": "ACCOUNT_NUMBER"
              },
              "value": "10173412345"
            },
            "type": {
              "schema": "CODE",
              "value": "CACC"
            }
          },
          "creditorAgent": {
            "clearingSystemMemberId": {
              "memberId": "888004"
            }
          },
          "ultimateCreditor": {
            "legalName": "Ultimate Creditor Name",
            "identification": {
              "schema": "ORGANISATION",
              "identifiers": [
                {
                  "schema": "BIC",
                  "BIC": "RY8PEG0L"
                }
              ]
            },
            "contactDetails": {
              "phoneNumber": "+27-86-0001234",
              "emailAddress": "collections@exampleloans.example.co.za"
            }
          },
          "debtor": {
            "legalName": "MR JOHN EXAMPLE"
          },
          "debtorAccount": {
            "identification": {
              "schema": "GENERIC",
              "scheme": {
                "schema": "PROPRIETARY",
                "value": "ACCOUNT_NUMBER"
              },
              "value": "10173412345"
            },
            "type": {
              "schema": "CODE",
              "value": "SVGS"
            }
          },
          "debtorAgent": {
            "clearingSystemMemberId": {
              "memberId": "888002"
            }
          }
        }
      }
    }
  }'

Responses

Accepted. RFC9110 - 202

Response

No content

Request suspension of an existing mandate

Request

This operation is asynchronous. The outcome is delivered via the outboundMandateStatusReport operation.

Instructs Electrum to send a mandate suspension request to the creditor's bank to suspend an existing mandate. The debtor and creditor may be at the same bank.

If a suspension request is sent by the client outside of a clearing house processing window for suspensions, the suspension will be sent to the clearing house in the next processing window.

Scheme	Applicable
ZA_AC	✓

Headers

traceparentstring(traceparent)^[A-Fa-f0-9]{2}\-[A-Fa-f0-9]{32}\-[A-Fa-f0-9]...

tracestatestring(tracestate)^[A-Za-z0-9=, _\*/@]{0,1024}$

Bodyapplication/jsonrequired

messageIdentifiersobject(MessageIdentifiers)required

Holds a point-to-point unique message identification string as well as a message's creation date time.

messageIdentifiers.creationDateTimestring(date-time)required

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

messageIdentifiers.messageIdentificationstring<= 35 charactersrequired

supplementaryDataobject(SupplementaryData)

A list of key-value pairs to support adding any supplementary/additional data to an Electrum Regulated Payments API message.

initiatingPartyobject(Party)

This model is the basic representation of a Party. It is expanded on depending on whether the party is a person or an organisation.

instructedAgentobject(InstitutionIdentification)

instructingAgentobject(InstitutionIdentification)

paymentSchemeobject(MandatePaymentScheme)required

Designates which scheme a mandate operation is associated with and describes scheme-specific information for the mandate operation where relevant.

paymentScheme.schemastring(PaymentSchemeName)required

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.

Enum"ZA_RTC""ZA_RPP""ZA_EFT""ZA_AC""ZA_RMS""CBPR_PLUS"

Discriminator

paymentScheme.schemeDataobject(ZaAcMandatePaymentSchemeData)required

South Africa specific supplementary data fields. These fields supplement the core mandate structure with local requirements.

paymentScheme.schemeData.authenticationTypestringrequired

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).

Enum"REAL_TIME""PREAUTH""BATCH""NOT_APPLICABLE"

paymentScheme.schemeData.collectionDayinteger[ 1 .. 99 ]

The Payer's preferred recurring day for collection from their bank account.

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).

Note: According to clearing rules, Debtor Banks are only required to enforce this strict date validation on Weekly and Monthly frequencies.

paymentScheme.schemeData.debitValueTypestring

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.

Enum"FIXED""VARIABLE""USAGE_BASED"

paymentScheme.schemeData.debtorBankMandateReferencestring<= 22 characters^[0-9]{4}20[0-9]{2}[0-1][0-9][0-3][0-9].{10}$...

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):

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.

paymentScheme.schemeData.mandateRequestTransactionIdentifierstring(MandateRequestTransactionIdentifier)<= 35 characters^\d{4}\d{4}-\d{2}-\d{2}\d{9}$

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 provided MRTI is used by Electrum.
If Electrum is the source of truth for mandate state the 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):

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 MRTI for the initiation request. If not provided by the client, Electrum generates one automatically.
Mandate Amendment Request: A new, unique 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).
Mandate Cancellation Request:
- In-flight cancellation: If cancelling a mandate request that is still in-flight (e.g. awaiting debtor authentication), the 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.
- Active mandate cancellation: If the mandate is already fully registered and active, a new, unique MRTI must be issued for the cancellation request. If not provided, Electrum determines the mandate state and applies the correct rule automatically.
Mandate Acceptance Report: The response echoes back the MRTI from the request being responded to. For API-level correlation, clients use originalMessageIdentifiers.messageIdentification instead.
Mandate Status Report: The status report echoes back the MRTI from the request being reported on. For API-level correlation, clients use originalMessageIdentifiers.messageIdentification instead.

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.

paymentScheme.schemeData.requestTransmissionNumberinteger(MandatePaymentSchemeRequestTransmissionNumber)[ 1 .. 4 ]

Sequence number for the message's transmission. Used exclusively for real-time (TT1/TT3) messages to track message retries. 1 = original message transmission, 2-4 = retries.

schemastringrequired

Value"MandateSuspensionRequest"

underlyingSuspensionDetailsobject(UnderlyingSuspensionDetails)required

Contains the details of the mandate suspension including the reason and original mandate reference.

underlyingSuspensionDetails.originalMandateobject(OriginalMandateReference)required

For mandate amendment, cancellation and suspension requests, originalMandate is required and the originalMandateIdentification cannot be used as the sole reference.

underlyingSuspensionDetails.originalMandate.originalMandateobject(Mandate)

Core mandate data structure containing all the details of a direct debit mandate.

underlyingSuspensionDetails.originalMandate.originalMandateIdentificationstring<= 35 characters

Unique identification to unambiguously identify the original mandate. Can be the mandateIdentification as assigned by the creditor or the mandate reference number as assigned by the debtor agent

underlyingSuspensionDetails.suspensionReasonobject(MandateSuspensionReason)required

Provides details about the reason for a mandate suspension.

Field Usage Guidelines: reason: For South African Mandate Schemes the reason for the suspension is specified as one of the below PROPRIETARY values:

CTAM - Contract Amended.
CTCA - Contract Cancellation Initiated by Debtor.
CTEX - Contract Expired.
MCFC - Mandate Suspended - Final Collection.
MCOC - Mandate Suspended - Once off Collection.
MSUC - Mandate Suspended after seven consecutive unsuccessful Collections.
MASC - Mandate Suspended - Account not in a state for Collections.
MADO - Mandate suspended due to no collection for a period.

underlyingSuspensionDetails.suspensionReason.additionalInformationArray of strings

underlyingSuspensionDetails.suspensionReason.originatorobject(Party)

This model is the basic representation of a Party. It is expanded on depending on whether the party is a person or an organisation.

underlyingSuspensionDetails.suspensionReason.reasonobject(MandateSuspensionReasonChoice)required

Specifies the reason for the suspension request of a mandate.

underlyingSuspensionDetails.suspensionReason.reason.schemastringrequired

Identifies the value as being a pre-defined code. Always CODE.

Discriminator

underlyingSuspensionDetails.suspensionReason.reason.valuestringrequired

CTAM - Contract Amended.
CTCA - Contract Cancellation Initiated by Debtor.
CTEX - Contract Expired.
MCFC - Mandate Suspended - Final Collection.
MCOC - Mandate Suspended - Once off Collection.
MSUC - Mandate Suspended after seven consecutive unsuccessful Collections.

Enum"CTAM""CTCA""CTEX""MCFC""MCOC""MSUC"

underlyingSuspensionDetails.suspensionRequestIdentificationstring(MandateSuspensionRequestIdentification)<= 35 characters^STP/\d{4}/20\d{2}-\d{2}-\d{2}/\d{9}$

Suspension Request Identification A unique transaction identifier used to unambiguously identify the mandate suspension request to the clearing house.

Important: Usage of suspensionRequestIdentification**.

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 suspensionRequestIdentification in the MandateSuspensionRequest. The format is validated and the provided suspensionRequestIdentification is used by Electrum.
If Electrum is the source of truth for mandate state the suspensionRequestIdentification should not be provided by the client when initiating new mandate suspension; Electrum will generate a compliant suspensionRequestIdentification automatically which will be echoed back to the client.

Lifecycle behaviour:

Mandate Suspension Request: The originating bank creates a new, unique suspensionRequestIdentification for the suspension request. If not provided by the client, Electrum generates one automatically.
Customer Payment Status Report: The suspensionRequestIdentification is echoed in CustomerPaymentStatusReports that confirm the outcome of a mandate suspension.

Structure (29 characters): The identifier is composed of 4 components separated by forward slashes (/), matching the pattern STP/<BankCode>/<Date>/<Sequence>:

Prefix (STP): Fixed string indicating a Suspension.
Bank Code (4 numeric): The 4-digit identifier of the initiating bank.
Date (10 alphanumeric): The date the suspension is generated in YYYY-MM-DD format.
Sequence Number (9 numeric): Mandate Suspension sequence number. Must be unique within the bank and date.

curl -i -X POST \
  https://example.com/path/payments/api/v1/mandates/outbound/suspension \
  -H 'Content-Type: application/json' \
  -H 'traceparent: string' \
  -H 'tracestate: string' \
  -d '{
    "messageIdentifiers": {
      "creationDateTime": "2019-08-24T14:15:22Z",
      "messageIdentification": "string"
    },
    "supplementaryData": {
      "property1": "string",
      "property2": "string"
    },
    "initiatingParty": {
      "address": {
        "addressLine": [
          "string"
        ],
        "addressType": "ADDR",
        "buildingName": "string",
        "buildingNumber": "string",
        "country": "string",
        "countrySubDivision": "string",
        "department": "string",
        "districtName": "string",
        "floor": "string",
        "postBox": "string",
        "postCode": "string",
        "room": "string",
        "streetName": "string",
        "subDepartment": "string",
        "townLocationName": "string",
        "townName": "string"
      },
      "contactDetails": {
        "emailAddress": "user@example.com",
        "mobileNumber": "string",
        "phoneNumber": "string"
      },
      "countryOfResidence": "string",
      "identification": {
        "identifiers": [
          {
            "identification": "string",
            "issuer": "string",
            "scheme": {
              "schema": "string",
              "value": "ARNU"
            }
          }
        ],
        "schema": "string"
      },
      "knownAsName": "string",
      "legalName": "string"
    },
    "instructedAgent": {
      "additionalIdentifications": [
        {
          "accountKnownAs": "string",
          "identifier": {
            "schema": "string",
            "value": "string"
          },
          "registeredSchemes": [
            "ZA_RTC"
          ]
        }
      ],
      "address": {
        "addressLine": [
          "string"
        ],
        "addressType": "ADDR",
        "buildingName": "string",
        "buildingNumber": "string",
        "country": "string",
        "countrySubDivision": "string",
        "department": "string",
        "districtName": "string",
        "floor": "string",
        "postBox": "string",
        "postCode": "string",
        "room": "string",
        "streetName": "string",
        "subDepartment": "string",
        "townLocationName": "string",
        "townName": "string"
      },
      "bicfi": "string",
      "branch": {
        "address": {
          "addressLine": [
            "string"
          ],
          "addressType": "ADDR",
          "buildingName": "string",
          "buildingNumber": "string",
          "country": "string",
          "countrySubDivision": "string",
          "department": "string",
          "districtName": "string",
          "floor": "string",
          "postBox": "string",
          "postCode": "string",
          "room": "string",
          "streetName": "string",
          "subDepartment": "string",
          "townLocationName": "string",
          "townName": "string"
        },
        "identification": "string",
        "name": "string"
      },
      "clearingSystemMemberId": {
        "clearingSystem": {
          "schema": "string",
          "value": "MA"
        },
        "memberId": "string"
      },
      "companyRegistration": "string",
      "lei": "string",
      "memberId": "string",
      "name": "string"
    },
    "instructingAgent": {
      "additionalIdentifications": [
        {
          "accountKnownAs": "string",
          "identifier": {
            "schema": "string",
            "value": "string"
          },
          "registeredSchemes": [
            "ZA_RTC"
          ]
        }
      ],
      "address": {
        "addressLine": [
          "string"
        ],
        "addressType": "ADDR",
        "buildingName": "string",
        "buildingNumber": "string",
        "country": "string",
        "countrySubDivision": "string",
        "department": "string",
        "districtName": "string",
        "floor": "string",
        "postBox": "string",
        "postCode": "string",
        "room": "string",
        "streetName": "string",
        "subDepartment": "string",
        "townLocationName": "string",
        "townName": "string"
      },
      "bicfi": "string",
      "branch": {
        "address": {
          "addressLine": [
            "string"
          ],
          "addressType": "ADDR",
          "buildingName": "string",
          "buildingNumber": "string",
          "country": "string",
          "countrySubDivision": "string",
          "department": "string",
          "districtName": "string",
          "floor": "string",
          "postBox": "string",
          "postCode": "string",
          "room": "string",
          "streetName": "string",
          "subDepartment": "string",
          "townLocationName": "string",
          "townName": "string"
        },
        "identification": "string",
        "name": "string"
      },
      "clearingSystemMemberId": {
        "clearingSystem": {
          "schema": "string",
          "value": "MA"
        },
        "memberId": "string"
      },
      "companyRegistration": "string",
      "lei": "string",
      "memberId": "string",
      "name": "string"
    },
    "paymentScheme": {
      "schema": "ZA_RTC",
      "schemeData": {
        "authenticationType": "REAL_TIME",
        "collectionDay": 1,
        "debitValueType": "FIXED",
        "debtorBankMandateReference": "string",
        "mandateRequestTransactionIdentifier": "string",
        "requestTransmissionNumber": 1
      }
    },
    "schema": "MandateSuspensionRequest",
    "underlyingSuspensionDetails": {
      "originalMandate": {
        "originalMandate": {
          "adjustment": {
            "adjustmentAmount": {
              "currency": "string",
              "value": 0.1
            },
            "adjustmentRate": 0.1,
            "category": {
              "schema": "string",
              "value": "MIAN"
            },
            "dateAdjustmentRuleIndicator": true
          },
          "authentication": {
            "channel": {
              "schema": "string",
              "value": "ATMA"
            },
            "date": "2019-08-24",
            "messageAuthenticationCode": "string"
          },
          "collectionAmount": {
            "currency": "string",
            "value": 0.1
          },
          "creditor": {
            "address": {
              "addressLine": [
                "string"
              ],
              "addressType": "ADDR",
              "buildingName": "string",
              "buildingNumber": "string",
              "country": "string",
              "countrySubDivision": "string",
              "department": "string",
              "districtName": "string",
              "floor": "string",
              "postBox": "string",
              "postCode": "string",
              "room": "string",
              "streetName": "string",
              "subDepartment": "string",
              "townLocationName": "string",
              "townName": "string"
            },
            "contactDetails": {
              "emailAddress": "user@example.com",
              "mobileNumber": "string",
              "phoneNumber": "string"
            },
            "countryOfResidence": "string",
            "identification": {
              "identifiers": [
                {}
              ],
              "schema": "string"
            },
            "knownAsName": "string",
            "legalName": "string"
          },
          "creditorAccount": {
            "currency": "string",
            "identification": {
              "schema": "string",
              "value": "string"
            },
            "name": "string",
            "proxy": {
              "namespace": "string",
              "schema": "string"
            },
            "type": {
              "schema": "string",
              "value": "CACC"
            }
          },
          "creditorAgent": {
            "additionalIdentifications": [
              {
                "accountKnownAs": "string",
                "identifier": {},
                "registeredSchemes": [
                  null
                ]
              }
            ],
            "address": {
              "addressLine": [
                "string"
              ],
              "addressType": "ADDR",
              "buildingName": "string",
              "buildingNumber": "string",
              "country": "string",
              "countrySubDivision": "string",
              "department": "string",
              "districtName": "string",
              "floor": "string",
              "postBox": "string",
              "postCode": "string",
              "room": "string",
              "streetName": "string",
              "subDepartment": "string",
              "townLocationName": "string",
              "townName": "string"
            },
            "bicfi": "string",
            "branch": {
              "address": {
                "addressLine": [
                  null
                ],
                "addressType": "ADDR",
                "buildingName": "string",
                "buildingNumber": "string",
                "country": "string",
                "countrySubDivision": "string",
                "department": "string",
                "districtName": "string",
                "floor": "string",
                "postBox": "string",
                "postCode": "string",
                "room": "string",
                "streetName": "string",
                "subDepartment": "string",
                "townLocationName": "string",
                "townName": "string"
              },
              "identification": "string",
              "name": "string"
            },
            "clearingSystemMemberId": {
              "clearingSystem": {
                "schema": "string",
                "value": "MA"
              },
              "memberId": "string"
            },
            "companyRegistration": "string",
            "lei": "string",
            "memberId": "string",
            "name": "string"
          },
          "creditorSchemeIdentification": {
            "address": {
              "addressLine": [
                "string"
              ],
              "addressType": "ADDR",
              "buildingName": "string",
              "buildingNumber": "string",
              "country": "string",
              "countrySubDivision": "string",
              "department": "string",
              "districtName": "string",
              "floor": "string",
              "postBox": "string",
              "postCode": "string",
              "room": "string",
              "streetName": "string",
              "subDepartment": "string",
              "townLocationName": "string",
              "townName": "string"
            },
            "contactDetails": {
              "emailAddress": "user@example.com",
              "mobileNumber": "string",
              "phoneNumber": "string"
            },
            "countryOfResidence": "string",
            "identification": {
              "identifiers": [
                {}
              ],
              "schema": "string"
            },
            "knownAsName": "string",
            "legalName": "string"
          },
          "debtor": {
            "address": {
              "addressLine": [
                "string"
              ],
              "addressType": "ADDR",
              "buildingName": "string",
              "buildingNumber": "string",
              "country": "string",
              "countrySubDivision": "string",
              "department": "string",
              "districtName": "string",
              "floor": "string",
              "postBox": "string",
              "postCode": "string",
              "room": "string",
              "streetName": "string",
              "subDepartment": "string",
              "townLocationName": "string",
              "townName": "string"
            },
            "contactDetails": {
              "emailAddress": "user@example.com",
              "mobileNumber": "string",
              "phoneNumber": "string"
            },
            "countryOfResidence": "string",
            "identification": {
              "identifiers": [
                {}
              ],
              "schema": "string"
            },
            "knownAsName": "string",
            "legalName": "string"
          },
          "debtorAccount": {
            "currency": "string",
            "identification": {
              "schema": "string",
              "value": "string"
            },
            "name": "string",
            "proxy": {
              "namespace": "string",
              "schema": "string"
            },
            "type": {
              "schema": "string",
              "value": "CACC"
            }
          },
          "debtorAgent": {
            "additionalIdentifications": [
              {
                "accountKnownAs": "string",
                "identifier": {},
                "registeredSchemes": [
                  null
                ]
              }
            ],
            "address": {
              "addressLine": [
                "string"
              ],
              "addressType": "ADDR",
              "buildingName": "string",
              "buildingNumber": "string",
              "country": "string",
              "countrySubDivision": "string",
              "department": "string",
              "districtName": "string",
              "floor": "string",
              "postBox": "string",
              "postCode": "string",
              "room": "string",
              "streetName": "string",
              "subDepartment": "string",
              "townLocationName": "string",
              "townName": "string"
            },
            "bicfi": "string",
            "branch": {
              "address": {
                "addressLine": [
                  null
                ],
                "addressType": "ADDR",
                "buildingName": "string",
                "buildingNumber": "string",
                "country": "string",
                "countrySubDivision": "string",
                "department": "string",
                "districtName": "string",
                "floor": "string",
                "postBox": "string",
                "postCode": "string",
                "room": "string",
                "streetName": "string",
                "subDepartment": "string",
                "townLocationName": "string",
                "townName": "string"
              },
              "identification": "string",
              "name": "string"
            },
            "clearingSystemMemberId": {
              "clearingSystem": {
                "schema": "string",
                "value": "MA"
              },
              "memberId": "string"
            },
            "companyRegistration": "string",
            "lei": "string",
            "memberId": "string",
            "name": "string"
          },
          "firstCollectionAmount": {
            "currency": "string",
            "value": 0.1
          },
          "mandateIdentification": "string",
          "mandateReference": "string",
          "mandateRequestIdentification": "string",
          "maximumAmount": {
            "currency": "string",
            "value": 0.1
          },
          "occurrences": {
            "finalCollectionDate": "2019-08-24",
            "firstCollectionDate": "2019-08-24",
            "frequency": {
              "dayOfMonth": 1,
              "schema": "MonthlyFrequency"
            },
            "sequenceType": "FRST",
            "validFrom": "2019-08-24",
            "validTo": "2019-08-24"
          },
          "reason": {
            "schema": "string",
            "value": "AC01"
          },
          "referredDocument": [
            {
              "documentIdentifier": "string",
              "relatedDate": "2019-08-24",
              "type": {
                "issuer": "string",
                "schema": "CODE"
              }
            }
          ],
          "trackingIndicator": true,
          "type": {
            "categoryPurpose": {
              "schema": "string",
              "value": "BONU"
            },
            "classification": {
              "schema": "string",
              "value": "FIXE"
            },
            "localInstrument": {
              "schema": "string",
              "value": "0000"
            },
            "serviceLevel": {
              "schema": "string",
              "value": "BKTR"
            }
          },
          "ultimateCreditor": {
            "address": {
              "addressLine": [
                "string"
              ],
              "addressType": "ADDR",
              "buildingName": "string",
              "buildingNumber": "string",
              "country": "string",
              "countrySubDivision": "string",
              "department": "string",
              "districtName": "string",
              "floor": "string",
              "postBox": "string",
              "postCode": "string",
              "room": "string",
              "streetName": "string",
              "subDepartment": "string",
              "townLocationName": "string",
              "townName": "string"
            },
            "contactDetails": {
              "emailAddress": "user@example.com",
              "mobileNumber": "string",
              "phoneNumber": "string"
            },
            "countryOfResidence": "string",
            "identification": {
              "identifiers": [
                {}
              ],
              "schema": "string"
            },
            "knownAsName": "string",
            "legalName": "string"
          },
          "ultimateDebtor": {
            "address": {
              "addressLine": [
                "string"
              ],
              "addressType": "ADDR",
              "buildingName": "string",
              "buildingNumber": "string",
              "country": "string",
              "countrySubDivision": "string",
              "department": "string",
              "districtName": "string",
              "floor": "string",
              "postBox": "string",
              "postCode": "string",
              "room": "string",
              "streetName": "string",
              "subDepartment": "string",
              "townLocationName": "string",
              "townName": "string"
            },
            "contactDetails": {
              "emailAddress": "user@example.com",
              "mobileNumber": "string",
              "phoneNumber": "string"
            },
            "countryOfResidence": "string",
            "identification": {
              "identifiers": [
                {}
              ],
              "schema": "string"
            },
            "knownAsName": "string",
            "legalName": "string"
          }
        },
        "originalMandateIdentification": "string"
      },
      "suspensionReason": {
        "additionalInformation": [
          "string"
        ],
        "originator": {
          "address": {
            "addressLine": [
              "string"
            ],
            "addressType": "ADDR",
            "buildingName": "string",
            "buildingNumber": "string",
            "country": "string",
            "countrySubDivision": "string",
            "department": "string",
            "districtName": "string",
            "floor": "string",
            "postBox": "string",
            "postCode": "string",
            "room": "string",
            "streetName": "string",
            "subDepartment": "string",
            "townLocationName": "string",
            "townName": "string"
          },
          "contactDetails": {
            "emailAddress": "user@example.com",
            "mobileNumber": "string",
            "phoneNumber": "string"
          },
          "countryOfResidence": "string",
          "identification": {
            "identifiers": [
              {
                "identification": "string",
                "issuer": "string",
                "scheme": {}
              }
            ],
            "schema": "string"
          },
          "knownAsName": "string",
          "legalName": "string"
        },
        "reason": {
          "schema": "string",
          "value": "CTAM"
        }
      },
      "suspensionRequestIdentification": "string"
    }
  }'

Responses

Accepted. RFC9110 - 202

Response

No content

Request information of an existing mandate

Request

This operation initiates a Request for Mandate Information to retrieve the current status and details of a mandate from the authoritative Mandate Register.

This operation is asynchronous. The outcome is delivered via the outboundMandateAcceptanceReport operation.

Usage :

Creditor Verify (Interbank): Instructs Electrum to send a request to the Debtor's Bank. This is used by a Creditor to verify that the Mandate Information stored on the Debtor Bank's register matches their records.
Debtor Inquiry (Hosted Store): Used by the Debtor Bank to retrieve mandate details from the Mandate Store to fulfill a request from the Debtor. This is only supported when Electrum hosts the Mandate Store.

The debtor and creditor may be at the same bank.

Scheme Data Notes:

authenticationType must be set to NOT_APPLICABLE — debtor authentication is not required for information requests.
requestTransmissionNumber should be set to 1 for the initial request.
mandateRequestTransactionIdentifier is optional — Electrum will generate a compliant MRTI if not provided.
originalMessageInformation is optional on the partner request — Electrum will populate it from the latest message recorded against the mandate before forwarding to the scheme.

Scheme	Applicable
ZA_AC	✓

Headers

traceparentstring(traceparent)^[A-Fa-f0-9]{2}\-[A-Fa-f0-9]{32}\-[A-Fa-f0-9]...

tracestatestring(tracestate)^[A-Za-z0-9=, _\*/@]{0,1024}$

Bodyapplication/jsonrequired

messageIdentifiersobject(MessageIdentifiers)required

Holds a point-to-point unique message identification string as well as a message's creation date time.

messageIdentifiers.creationDateTimestring(date-time)required

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

messageIdentifiers.messageIdentificationstring<= 35 charactersrequired

supplementaryDataobject(SupplementaryData)

A list of key-value pairs to support adding any supplementary/additional data to an Electrum Regulated Payments API message.

initiatingPartyobject(Party)

This model is the basic representation of a Party. It is expanded on depending on whether the party is a person or an organisation.

instructedAgentobject(InstitutionIdentification)

instructingAgentobject(InstitutionIdentification)

paymentSchemeobject(MandatePaymentScheme)required

Designates which scheme a mandate operation is associated with and describes scheme-specific information for the mandate operation where relevant.

paymentScheme.schemastring(PaymentSchemeName)required

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.

Enum"ZA_RTC""ZA_RPP""ZA_EFT""ZA_AC""ZA_RMS""CBPR_PLUS"

Discriminator

paymentScheme.schemeDataobject(ZaAcMandatePaymentSchemeData)required

South Africa specific supplementary data fields. These fields supplement the core mandate structure with local requirements.

paymentScheme.schemeData.authenticationTypestringrequired

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).

Enum"REAL_TIME""PREAUTH""BATCH""NOT_APPLICABLE"

paymentScheme.schemeData.collectionDayinteger[ 1 .. 99 ]

The Payer's preferred recurring day for collection from their bank account.

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).

Note: According to clearing rules, Debtor Banks are only required to enforce this strict date validation on Weekly and Monthly frequencies.

paymentScheme.schemeData.debitValueTypestring

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.

Enum"FIXED""VARIABLE""USAGE_BASED"

paymentScheme.schemeData.debtorBankMandateReferencestring<= 22 characters^[0-9]{4}20[0-9]{2}[0-1][0-9][0-3][0-9].{10}$...

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):

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.

paymentScheme.schemeData.mandateRequestTransactionIdentifierstring(MandateRequestTransactionIdentifier)<= 35 characters^\d{4}\d{4}-\d{2}-\d{2}\d{9}$

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 provided MRTI is used by Electrum.
If Electrum is the source of truth for mandate state the 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):

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 MRTI for the initiation request. If not provided by the client, Electrum generates one automatically.
Mandate Amendment Request: A new, unique 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).
Mandate Cancellation Request:
- In-flight cancellation: If cancelling a mandate request that is still in-flight (e.g. awaiting debtor authentication), the 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.
- Active mandate cancellation: If the mandate is already fully registered and active, a new, unique MRTI must be issued for the cancellation request. If not provided, Electrum determines the mandate state and applies the correct rule automatically.
Mandate Acceptance Report: The response echoes back the MRTI from the request being responded to. For API-level correlation, clients use originalMessageIdentifiers.messageIdentification instead.
Mandate Status Report: The status report echoes back the MRTI from the request being reported on. For API-level correlation, clients use originalMessageIdentifiers.messageIdentification instead.

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.

paymentScheme.schemeData.requestTransmissionNumberinteger(MandatePaymentSchemeRequestTransmissionNumber)[ 1 .. 4 ]

Sequence number for the message's transmission. Used exclusively for real-time (TT1/TT3) messages to track message retries. 1 = original message transmission, 2-4 = retries.

schemastringrequired

Value"MandateInformationRequest"

underlyingCopyDetailsobject(UnderlyingCopyDetails)required

Contains the details of the mandate copy request including the original mandate reference.

underlyingCopyDetails.mandateStatusobject(MandateStatus)

Current status of a mandate.

underlyingCopyDetails.originalMandateobject(OriginalMandateReference)required

For mandate amendment, cancellation and suspension requests, originalMandate is required and the originalMandateIdentification cannot be used as the sole reference.

underlyingCopyDetails.originalMandate.originalMandateobject(Mandate)

Core mandate data structure containing all the details of a direct debit mandate.

underlyingCopyDetails.originalMandate.originalMandateIdentificationstring<= 35 characters

Unique identification to unambiguously identify the original mandate. Can be the mandateIdentification as assigned by the creditor or the mandate reference number as assigned by the debtor agent

underlyingCopyDetails.originalMessageInformationobject(OriginalMandateMessageInformation)

curl -i -X POST \
  https://example.com/path/payments/api/v1/mandates/outbound/information-request \
  -H 'Content-Type: application/json' \
  -H 'traceparent: string' \
  -H 'tracestate: string' \
  -d '{
    "schema": "MandateInformationRequest",
    "messageIdentifiers": {
      "messageIdentification": "3c004e038bd3469d99d112681ca1166f",
      "creationDateTime": "2026-01-26T07:58:00Z"
    },
    "paymentScheme": {
      "schema": "ZA_AC",
      "schemeData": {
        "authenticationType": "NOT_APPLICABLE",
        "requestTransmissionNumber": 1
      }
    },
    "initiatingParty": {
      "legalName": "EXAMPLE LOANS"
    },
    "underlyingCopyDetails": {
      "originalMandate": {
        "originalMandateIdentification": "RGCAP1900000000000A1"
      }
    }
  }'

Responses

Accepted. RFC9110 - 202

Response

No content

Send a mandate status report relating to an outbound mandate maintenance operation

Request

This operation is asynchronous.

Use cases include:

Mandate management operation rejection (e.g. validation failure)
Acknowledgement of Mandate Acceptance Report

Scheme	Applicable
ZA_AC	✓

Headers

traceparentstring(traceparent)^[A-Fa-f0-9]{2}\-[A-Fa-f0-9]{32}\-[A-Fa-f0-9]...

tracestatestring(tracestate)^[A-Za-z0-9=, _\*/@]{0,1024}$

Bodyapplication/jsonrequired

messageIdentifiersobject(MessageIdentifiers)required

Holds a point-to-point unique message identification string as well as a message's creation date time.

messageIdentifiers.creationDateTimestring(date-time)required

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

messageIdentifiers.messageIdentificationstring<= 35 charactersrequired

supplementaryDataobject(SupplementaryData)

A list of key-value pairs to support adding any supplementary/additional data to an Electrum Regulated Payments API message.

originalMessageIdentifiersobject(MessageIdentifiers)required

Holds a point-to-point unique message identification string as well as a message's creation date time.

originalMessageIdentifiers.creationDateTimestring(date-time)required

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

originalMessageIdentifiers.messageIdentificationstring<= 35 charactersrequired

instructedAgentobject(InstitutionIdentification)

instructingAgentobject(InstitutionIdentification)

mandateInformationobject(MandateInformation)

Provides a reference to the direct debit mandate signed between the creditor and the debtor.

Note: This model is not relevant to the ZA_EFT scheme. Electrum will not process these fields for EFT payments (e.g. tracking days are not honoured for EFT).

originalMessageNameIdentificationstring<= 35 charactersrequired

Specifies the original message name identifier to which the message refers. In ELPAPI, this should be the ELPAPI message type name (e.g. MandateInitiationRequest, MandateAmendmentRequest, CreditTransfer).

paymentSchemeobject(CustomerPaymentStatusReportPaymentScheme)required

Designates which scheme a customer payment status report is associated with and describes scheme-specific information for the customer payment status report.

paymentScheme.schemastring(PaymentSchemeName)required

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.

Enum"ZA_RTC""ZA_RPP""ZA_EFT""ZA_AC""ZA_RMS""CBPR_PLUS"

Discriminator

paymentScheme.schemeDataobject(ZaAcCustomerPaymentStatusReportPaymentSchemeData)required

The mandateRequestTransactionIdentifier and suspensionRequestIdentification are mutually exclusive fields

If the status report is responding to a standard mandate operation (Initiation, Amendment, Cancellation), it echoes the MRTI.
If the status report is responding to a Suspension, it echoes the Suspension Request Identification.

paymentScheme.schemeData.mandateRequestTransactionIdentifierstring(MandateRequestTransactionIdentifier)<= 35 characters^\d{4}\d{4}-\d{2}-\d{2}\d{9}$

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 provided MRTI is used by Electrum.
If Electrum is the source of truth for mandate state the 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):

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 MRTI for the initiation request. If not provided by the client, Electrum generates one automatically.
Mandate Amendment Request: A new, unique 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).
Mandate Cancellation Request:
- In-flight cancellation: If cancelling a mandate request that is still in-flight (e.g. awaiting debtor authentication), the 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.
- Active mandate cancellation: If the mandate is already fully registered and active, a new, unique MRTI must be issued for the cancellation request. If not provided, Electrum determines the mandate state and applies the correct rule automatically.
Mandate Acceptance Report: The response echoes back the MRTI from the request being responded to. For API-level correlation, clients use originalMessageIdentifiers.messageIdentification instead.
Mandate Status Report: The status report echoes back the MRTI from the request being reported on. For API-level correlation, clients use originalMessageIdentifiers.messageIdentification instead.

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.

paymentScheme.schemeData.requestTransmissionNumberinteger(MandatePaymentSchemeRequestTransmissionNumber)[ 1 .. 4 ]

Sequence number for the message's transmission. Used exclusively for real-time (TT1/TT3) messages to track message retries. 1 = original message transmission, 2-4 = retries.

paymentScheme.schemeData.suspensionRequestIdentificationstring(MandateSuspensionRequestIdentification)<= 35 characters^STP/\d{4}/20\d{2}-\d{2}-\d{2}/\d{9}$

Suspension Request Identification A unique transaction identifier used to unambiguously identify the mandate suspension request to the clearing house.

Important: Usage of suspensionRequestIdentification**.

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 suspensionRequestIdentification in the MandateSuspensionRequest. The format is validated and the provided suspensionRequestIdentification is used by Electrum.
If Electrum is the source of truth for mandate state the suspensionRequestIdentification should not be provided by the client when initiating new mandate suspension; Electrum will generate a compliant suspensionRequestIdentification automatically which will be echoed back to the client.

Lifecycle behaviour:

Mandate Suspension Request: The originating bank creates a new, unique suspensionRequestIdentification for the suspension request. If not provided by the client, Electrum generates one automatically.
Customer Payment Status Report: The suspensionRequestIdentification is echoed in CustomerPaymentStatusReports that confirm the outcome of a mandate suspension.

Structure (29 characters): The identifier is composed of 4 components separated by forward slashes (/), matching the pattern STP/<BankCode>/<Date>/<Sequence>:

Prefix (STP): Fixed string indicating a Suspension.
Bank Code (4 numeric): The 4-digit identifier of the initiating bank.
Date (10 alphanumeric): The date the suspension is generated in YYYY-MM-DD format.
Sequence Number (9 numeric): Mandate Suspension sequence number. Must be unique within the bank and date.

schemastringrequired

Value"CustomerPaymentStatusReport"

statusobject(Status)required

status.outcomestringrequired

APPROVED: The instruction has been approved.
CANCELLED: The instruction has been cancelled.
PENDING: The instruction is pending.
REJECTED: The instruction has been rejected.

Enum"APPROVED""CANCELLED""PENDING""REJECTED"

status.reasonInfoArray of objects(StatusReasonInfo)non-empty

A list of StatusReasonInfo values providing detailed reason information for the outcome.

curl -i -X POST \
  https://example.com/path/payments/api/v1/mandates/outbound/status-report \
  -H 'Content-Type: application/json' \
  -H 'traceparent: string' \
  -H 'tracestate: string' \
  -d '{
    "schema": "CustomerPaymentStatusReport",
    "messageIdentifiers": {
      "messageIdentification": "100/MANSR/00210010/20190513/000002",
      "creationDateTime": "2019-05-13T15:16:05Z"
    },
    "originalMessageIdentifiers": {
      "messageIdentification": "100/MANIN/00210007/20190305/000511",
      "creationDateTime": "2019-03-05T10:04:44Z"
    },
    "originalMessageNameIdentification": "MandateInitiationRequest",
    "paymentScheme": {
      "schema": "ZA_AC",
      "schemeData": {
        "mandateRequestTransactionIdentifier": "00072019-03-05000000086",
        "requestTransmissionNumber": 1
      }
    },
    "status": {
      "outcome": "REJECTED",
      "reasonInfo": [
        {
          "reason": {
            "schema": "PROPRIETARY",
            "value": "901103"
          },
          "additionalInformation": "Invalid Instalment Frequency"
        },
        {
          "reason": {
            "schema": "PROPRIETARY",
            "value": "901106"
          },
          "additionalInformation": "Invalid First Collection Date on mandate"
        }
      ]
    },
    "mandateInformation": {
      "mandateIdentification": "REGRCAP2019042615"
    }
  }'

Responses

Accepted. RFC9110 - 202

Response

No content

Respond to an inbound mandate request

Request

This operation is asynchronous. It is the response to inbound mandate operations:

Delivers the acceptance or rejection of a mandate initiation, amendment or cancellation request received from a creditor bank. Also used when responding to a mandate information request.

The original request is referenced via the originalMessageIdentifiers field (from the base response message) and the originalMessageInformation.messageNameIdentification field indicates the type of the original request. The debtor and creditor may be at the same bank.

Scheme	Applicable
ZA_AC	✓

Headers

traceparentstring(traceparent)^[A-Fa-f0-9]{2}\-[A-Fa-f0-9]{32}\-[A-Fa-f0-9]...

tracestatestring(tracestate)^[A-Za-z0-9=, _\*/@]{0,1024}$

Bodyapplication/jsonrequired

messageIdentifiersobject(MessageIdentifiers)required

Holds a point-to-point unique message identification string as well as a message's creation date time.

messageIdentifiers.creationDateTimestring(date-time)required

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

messageIdentifiers.messageIdentificationstring<= 35 charactersrequired

supplementaryDataobject(SupplementaryData)

A list of key-value pairs to support adding any supplementary/additional data to an Electrum Regulated Payments API message.

originalMessageIdentifiersobject(MessageIdentifiers)required

Holds a point-to-point unique message identification string as well as a message's creation date time.

originalMessageIdentifiers.creationDateTimestring(date-time)required

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

originalMessageIdentifiers.messageIdentificationstring<= 35 charactersrequired

initiatingPartyobject(Party)

This model is the basic representation of a Party. It is expanded on depending on whether the party is a person or an organisation.

instructedAgentobject(InstitutionIdentification)

instructingAgentobject(InstitutionIdentification)

paymentSchemeobject(MandatePaymentScheme)required

Designates which scheme a mandate operation is associated with and describes scheme-specific information for the mandate operation where relevant.

paymentScheme.schemastring(PaymentSchemeName)required

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.

Enum"ZA_RTC""ZA_RPP""ZA_EFT""ZA_AC""ZA_RMS""CBPR_PLUS"

Discriminator

paymentScheme.schemeDataobject(ZaAcMandatePaymentSchemeData)required

South Africa specific supplementary data fields. These fields supplement the core mandate structure with local requirements.

paymentScheme.schemeData.authenticationTypestringrequired

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).

Enum"REAL_TIME""PREAUTH""BATCH""NOT_APPLICABLE"

paymentScheme.schemeData.collectionDayinteger[ 1 .. 99 ]

The Payer's preferred recurring day for collection from their bank account.

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).

Note: According to clearing rules, Debtor Banks are only required to enforce this strict date validation on Weekly and Monthly frequencies.

paymentScheme.schemeData.debitValueTypestring

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.

Enum"FIXED""VARIABLE""USAGE_BASED"

paymentScheme.schemeData.debtorBankMandateReferencestring<= 22 characters^[0-9]{4}20[0-9]{2}[0-1][0-9][0-3][0-9].{10}$...

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):

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.

paymentScheme.schemeData.mandateRequestTransactionIdentifierstring(MandateRequestTransactionIdentifier)<= 35 characters^\d{4}\d{4}-\d{2}-\d{2}\d{9}$

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 provided MRTI is used by Electrum.
If Electrum is the source of truth for mandate state the 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):

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 MRTI for the initiation request. If not provided by the client, Electrum generates one automatically.
Mandate Amendment Request: A new, unique 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).
Mandate Cancellation Request:
- In-flight cancellation: If cancelling a mandate request that is still in-flight (e.g. awaiting debtor authentication), the 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.
- Active mandate cancellation: If the mandate is already fully registered and active, a new, unique MRTI must be issued for the cancellation request. If not provided, Electrum determines the mandate state and applies the correct rule automatically.
Mandate Acceptance Report: The response echoes back the MRTI from the request being responded to. For API-level correlation, clients use originalMessageIdentifiers.messageIdentification instead.
Mandate Status Report: The status report echoes back the MRTI from the request being reported on. For API-level correlation, clients use originalMessageIdentifiers.messageIdentification instead.

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.

paymentScheme.schemeData.requestTransmissionNumberinteger(MandatePaymentSchemeRequestTransmissionNumber)[ 1 .. 4 ]

Sequence number for the message's transmission. Used exclusively for real-time (TT1/TT3) messages to track message retries. 1 = original message transmission, 2-4 = retries.

schemastringrequired

Value"MandateAcceptanceReport"

underlyingAcceptanceDetailsobject(UnderlyingAcceptanceDetails)required

Contains the core information regarding the acceptance or rejection of the mandate maintenance request.

underlyingAcceptanceDetails.acceptanceResultobject(MandateAcceptanceResult)required

Result of a mandate maintenance request.

underlyingAcceptanceDetails.acceptanceResult.acceptedbooleanrequired

Indicates whether the mandate maintenance request was accepted (true) or rejected (false).

underlyingAcceptanceDetails.acceptanceResult.additionalRejectionInformationArray of strings

Additional information about the rejection reason.

underlyingAcceptanceDetails.acceptanceResult.rejectionReasonobject(MandateReason)

Specifies the reason for a mandate action (amendment, cancellation, rejection).

underlyingAcceptanceDetails.originalMandateobject(OriginalMandateReference)

For mandate amendment, cancellation and suspension requests, originalMandate is required and the originalMandateIdentification cannot be used as the sole reference.

underlyingAcceptanceDetails.originalMessageInformationobject(OriginalMandateMessageInformation)

curl -i -X POST \
  https://example.com/path/payments/api/v1/mandates/inbound/acceptance-report \
  -H 'Content-Type: application/json' \
  -H 'traceparent: string' \
  -H 'tracestate: string' \
  -d '{
    "schema": "MandateAcceptanceReport",
    "messageIdentifiers": {
      "messageIdentification": "3c004e038bd3469d99d112681ca1166f",
      "creationDateTime": "2019-05-13T15:15:43Z"
    },
    "originalMessageIdentifiers": {
      "messageIdentification": "100/MANIN/00210007/20190305/000511",
      "creationDateTime": "2019-03-05T10:04:44Z"
    },
    "paymentScheme": {
      "schema": "ZA_AC",
      "schemeData": {
        "mandateRequestTransactionIdentifier": "00072018-03-19000000098",
        "debtorBankMandateReference": "0003202501015177310122",
        "authenticationType": "REAL_TIME",
        "requestTransmissionNumber": 1,
        "collectionDay": 30,
        "debitValueType": "FIXED"
      }
    },
    "initiatingParty": {
      "legalName": "EXAMPLE LOANS"
    },
    "underlyingAcceptanceDetails": {
      "acceptanceResult": {
        "accepted": false,
        "rejectionReason": {
          "schema": "PROPRIETARY",
          "value": "NRSP"
        },
        "additionalRejectionInformation": [
          "Mandate initiation timed out waiting for debtor authorisation"
        ]
      },
      "originalMandate": {
        "originalMandate": {
          "mandateIdentification": "REGRCAP2019042615",
          "mandateRequestIdentification": "REG201926123",
          "trackingIndicator": true,
          "type": {
            "localInstrument": {
              "schema": "PROPRIETARY",
              "value": "0228"
            }
          },
          "occurrences": {
            "sequenceType": "RCUR",
            "frequency": {
              "schema": "MonthlyFrequency",
              "dayOfMonth": 15
            },
            "validFrom": "2019-04-26",
            "firstCollectionDate": "2019-04-30"
          },
          "collectionAmount": {
            "value": 100,
            "currency": "ZAR"
          },
          "maximumAmount": {
            "value": 120,
            "currency": "ZAR"
          },
          "creditor": {
            "legalName": "Creditor Name",
            "identification": {
              "schema": "ORGANISATION",
              "identifiers": [
                {
                  "schema": "BIC",
                  "BIC": "RY8PEG0L"
                }
              ]
            }
          },
          "debtor": {
            "legalName": "Debtor Name",
            "identification": {
              "schema": "PERSON",
              "identifiers": [
                {
                  "identification": "I/9905140859123",
                  "scheme": {
                    "schema": "CODE",
                    "value": "NIDN"
                  }
                }
              ]
            }
          },
          "debtorAccount": {
            "identification": {
              "schema": "GENERIC",
              "scheme": {
                "schema": "PROPRIETARY",
                "value": "ACCOUNT_NUMBER"
              },
              "value": "10173412345"
            },
            "type": {
              "schema": "CODE",
              "value": "SVGS"
            }
          },
          "debtorAgent": {
            "clearingSystemMemberId": {
              "memberId": "470010"
            }
          },
          "authentication": {
            "date": "2019-04-03",
            "channel": {
              "schema": "PROPRIETARY",
              "value": "NC03"
            }
          }
        }
      }
    }
  }'

Responses

Accepted. RFC9110 - 202

Response

No content

Send a mandate status report relating to an inbound mandate maintenance operation

Request

This operation is asynchronous.

Use cases include:

Mandate maintenance acknowledgment (e.g., validation passed, debtor contacted)
Mandate maintenance rejection (validation failure)
To indicate whether a mandate suspension was accepted or rejected. Is also used to respond to the inboundMandateSuspension operation

Scheme	Applicable
ZA_AC	✓

Headers

traceparentstring(traceparent)^[A-Fa-f0-9]{2}\-[A-Fa-f0-9]{32}\-[A-Fa-f0-9]...

tracestatestring(tracestate)^[A-Za-z0-9=, _\*/@]{0,1024}$

Bodyapplication/jsonrequired

messageIdentifiersobject(MessageIdentifiers)required

Holds a point-to-point unique message identification string as well as a message's creation date time.

messageIdentifiers.creationDateTimestring(date-time)required

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

messageIdentifiers.messageIdentificationstring<= 35 charactersrequired

supplementaryDataobject(SupplementaryData)

A list of key-value pairs to support adding any supplementary/additional data to an Electrum Regulated Payments API message.

originalMessageIdentifiersobject(MessageIdentifiers)required

Holds a point-to-point unique message identification string as well as a message's creation date time.

originalMessageIdentifiers.creationDateTimestring(date-time)required

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

originalMessageIdentifiers.messageIdentificationstring<= 35 charactersrequired

instructedAgentobject(InstitutionIdentification)

instructingAgentobject(InstitutionIdentification)

mandateInformationobject(MandateInformation)

Provides a reference to the direct debit mandate signed between the creditor and the debtor.

Note: This model is not relevant to the ZA_EFT scheme. Electrum will not process these fields for EFT payments (e.g. tracking days are not honoured for EFT).

originalMessageNameIdentificationstring<= 35 charactersrequired

paymentSchemeobject(CustomerPaymentStatusReportPaymentScheme)required

Designates which scheme a customer payment status report is associated with and describes scheme-specific information for the customer payment status report.

paymentScheme.schemastring(PaymentSchemeName)required

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.

Enum"ZA_RTC""ZA_RPP""ZA_EFT""ZA_AC""ZA_RMS""CBPR_PLUS"

Discriminator

paymentScheme.schemeDataobject(ZaAcCustomerPaymentStatusReportPaymentSchemeData)required

The mandateRequestTransactionIdentifier and suspensionRequestIdentification are mutually exclusive fields

If the status report is responding to a standard mandate operation (Initiation, Amendment, Cancellation), it echoes the MRTI.
If the status report is responding to a Suspension, it echoes the Suspension Request Identification.

paymentScheme.schemeData.mandateRequestTransactionIdentifierstring(MandateRequestTransactionIdentifier)<= 35 characters^\d{4}\d{4}-\d{2}-\d{2}\d{9}$

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 provided MRTI is used by Electrum.
If Electrum is the source of truth for mandate state the 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):

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 MRTI for the initiation request. If not provided by the client, Electrum generates one automatically.
Mandate Amendment Request: A new, unique 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).
Mandate Cancellation Request:
- In-flight cancellation: If cancelling a mandate request that is still in-flight (e.g. awaiting debtor authentication), the 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.
- Active mandate cancellation: If the mandate is already fully registered and active, a new, unique MRTI must be issued for the cancellation request. If not provided, Electrum determines the mandate state and applies the correct rule automatically.
Mandate Acceptance Report: The response echoes back the MRTI from the request being responded to. For API-level correlation, clients use originalMessageIdentifiers.messageIdentification instead.
Mandate Status Report: The status report echoes back the MRTI from the request being reported on. For API-level correlation, clients use originalMessageIdentifiers.messageIdentification instead.

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.

paymentScheme.schemeData.requestTransmissionNumberinteger(MandatePaymentSchemeRequestTransmissionNumber)[ 1 .. 4 ]

Sequence number for the message's transmission. Used exclusively for real-time (TT1/TT3) messages to track message retries. 1 = original message transmission, 2-4 = retries.

paymentScheme.schemeData.suspensionRequestIdentificationstring(MandateSuspensionRequestIdentification)<= 35 characters^STP/\d{4}/20\d{2}-\d{2}-\d{2}/\d{9}$

Suspension Request Identification A unique transaction identifier used to unambiguously identify the mandate suspension request to the clearing house.

Important: Usage of suspensionRequestIdentification**.

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 suspensionRequestIdentification in the MandateSuspensionRequest. The format is validated and the provided suspensionRequestIdentification is used by Electrum.
If Electrum is the source of truth for mandate state the suspensionRequestIdentification should not be provided by the client when initiating new mandate suspension; Electrum will generate a compliant suspensionRequestIdentification automatically which will be echoed back to the client.

Lifecycle behaviour:

Mandate Suspension Request: The originating bank creates a new, unique suspensionRequestIdentification for the suspension request. If not provided by the client, Electrum generates one automatically.
Customer Payment Status Report: The suspensionRequestIdentification is echoed in CustomerPaymentStatusReports that confirm the outcome of a mandate suspension.

Structure (29 characters): The identifier is composed of 4 components separated by forward slashes (/), matching the pattern STP/<BankCode>/<Date>/<Sequence>:

Prefix (STP): Fixed string indicating a Suspension.
Bank Code (4 numeric): The 4-digit identifier of the initiating bank.
Date (10 alphanumeric): The date the suspension is generated in YYYY-MM-DD format.
Sequence Number (9 numeric): Mandate Suspension sequence number. Must be unique within the bank and date.

schemastringrequired

Value"CustomerPaymentStatusReport"

statusobject(Status)required

status.outcomestringrequired

APPROVED: The instruction has been approved.
CANCELLED: The instruction has been cancelled.
PENDING: The instruction is pending.
REJECTED: The instruction has been rejected.

Enum"APPROVED""CANCELLED""PENDING""REJECTED"

status.reasonInfoArray of objects(StatusReasonInfo)non-empty

A list of StatusReasonInfo values providing detailed reason information for the outcome.

curl -i -X POST \
  https://example.com/path/payments/api/v1/mandates/inbound/status-report \
  -H 'Content-Type: application/json' \
  -H 'traceparent: string' \
  -H 'tracestate: string' \
  -d '{
    "schema": "CustomerPaymentStatusReport",
    "messageIdentifiers": {
      "messageIdentification": "100/MANSR/00210010/20190513/000002",
      "creationDateTime": "2019-05-13T15:16:05Z"
    },
    "originalMessageIdentifiers": {
      "messageIdentification": "100/MANIN/00210007/20190305/000511",
      "creationDateTime": "2019-03-05T10:04:44Z"
    },
    "originalMessageNameIdentification": "MandateInitiationRequest",
    "paymentScheme": {
      "schema": "ZA_AC",
      "schemeData": {
        "mandateRequestTransactionIdentifier": "00072019-03-05000000086",
        "requestTransmissionNumber": 1
      }
    },
    "status": {
      "outcome": "REJECTED",
      "reasonInfo": [
        {
          "reason": {
            "schema": "PROPRIETARY",
            "value": "901103"
          },
          "additionalInformation": "Invalid Instalment Frequency"
        },
        {
          "reason": {
            "schema": "PROPRIETARY",
            "value": "901106"
          },
          "additionalInformation": "Invalid First Collection Date on mandate"
        }
      ]
    },
    "mandateInformation": {
      "mandateIdentification": "REGRCAP2019042615"
    }
  }'

Responses

Accepted. RFC9110 - 202

Response

No content

Schema

operational

Operations

bulk

Operations

accounts

Operations

account-verification

Operations

Electrum Regulated Payments API (26.0.0)

transactional

financial

credit-transfer

direct-debit

payment-return

account-management

proxy

scheme-inquiry

identifier-determination

identifier-verification

request-to-pay

funds-management

refund

risk-assessment

fraud-assessment

mandate-management

Initiate a new mandate request

RequestExpand all

Responses

Was this page helpful?

Request an amendment to an existing mandate

RequestExpand all

Responses

Was this page helpful?

Request cancellation of an existing mandate

RequestExpand all

Responses

Was this page helpful?

Request suspension of an existing mandate

RequestExpand all

Responses

Was this page helpful?

Request information of an existing mandate

RequestExpand all

Responses

Was this page helpful?

Send a mandate status report relating to an outbound mandate maintenance operation

RequestExpand all

Responses

Was this page helpful?

Respond to an inbound mandate request

RequestExpand all

Responses

Was this page helpful?

Send a mandate status report relating to an inbound mandate maintenance operation

RequestExpand all

Responses

Was this page helpful?

Schema

operational

bulk

accounts

account-verification

Request

Request

Request

Request

Request

Request

Request

Request