Electrum Regulated Payments Partner API (26.1.1)

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

In the ZA_AC scheme, the Collection Day is a rigid, legally binding clearing rule that is strictly evaluated relative to the mandate's Frequency. The interpretation of this integer changes based on the frequency type:

• Monthly, Quarterly, Bi-annually, Annually, Once-off: Values 1 to 30 represent the exact calendar day of the month. 99 strictly represents the "Last Day" of the month (e.g., automatically adjusting for February 28th/29th). Note: 31 is not a valid input.
• Weekly: Values 1 to 7 represent the day of the week (1 = Monday, 7 = Sunday).
• Fortnightly: Values 1 to 14 represent the day within the two-week cycle (1 to 7 for week one; 8 to 14 for week two).
• Monthly by Rule: Values map to specific occurrences (e.g., 1 = Last Monday, 7 = First Monday, 14 = 2nd Last Day).

Interbank Validation Rules: The Debtor Bank is required to store this exact day in their Mandate Register. If the mandate's dateAdjustmentRule is set to 'N' (No), the Debtor Bank will strictly validate incoming collections against this day. If a collection's Action Date does not exactly match this collectionDay (or the immediately following Processing Day), the Debtor Bank will trigger an upfront rejection.

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

This dictates strict interbank validation rules for how collection amounts are calculated, capped, and adjusted over the life of the mandate.

The rules for each type are:

• FIXED: Used for contracts where an upfront, calculated Instalment Amount is the basis for normal collections. Regular collections are strictly validated and cannot exceed this Instalment Amount. The Adjustment Category for a fixed mandate must strictly be 'NEVR' (Never).
• VARIABLE: Used for contracts where an upfront Instalment Amount is calculated but can be amended by the Creditor based on pre-agreed variables, such as annual increases or interest rate changes. Regular collections cannot exceed the currently active Instalment Amount.
• USAGE_BASED: Used for contracts where the collection amount fluctuates depending on the Payer's usage of a product or service during the payment cycle. Unlike Fixed and Variable mandates, the regular Instalment Amount is optional, and interbank validation is instead performed strictly against a mandatory Maximum Collection Amount.

The Mandate Reference Number (MRN) assigned by the debtor bank upon mandate acceptance. This is the official, unique industry-wide identification number for the mandate that is unique for the mandate's entire lifecycle (including time in archives).

It is returned in the acceptance report and must be included in subsequent mandate amendment, and suspension requests.

Not to be confused with mandateIdentification (creditor's internal ID), mandateRequestTransactionIdentifier (MRTI), or mandateReference (mandate management app reference).

Structure (22 characters):

• Bank Number (4 numeric): The 4-digit identifier of the Debtor Bank.
• Mandate Creation Date (8 numeric): The date the mandate was successfully registered, formatted strictly as YYYYMMDD.
• Free Format (10 alphanumeric): A unique identifier or sequence generated by the Debtor Bank.

Mandate Request Transaction Identifier (MRTI) A unique transaction identifier used for matching multiple messages to a single transaction. This identifier is created for each new mandate request to uniquely identify the transaction within the Authenticated Collections scheme.

Important: Usage of mandateRequestTransactionIdentifier**.

• If the client is the host of the mandate register and is the source of truth for mandate state the client is required to always populate the MRTI. The format is validated and the 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.

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.

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

In the ZA_AC scheme, the Collection Day is a rigid, legally binding clearing rule that is strictly evaluated relative to the mandate's Frequency. The interpretation of this integer changes based on the frequency type:

• Monthly, Quarterly, Bi-annually, Annually, Once-off: Values 1 to 30 represent the exact calendar day of the month. 99 strictly represents the "Last Day" of the month (e.g., automatically adjusting for February 28th/29th). Note: 31 is not a valid input.
• Weekly: Values 1 to 7 represent the day of the week (1 = Monday, 7 = Sunday).
• Fortnightly: Values 1 to 14 represent the day within the two-week cycle (1 to 7 for week one; 8 to 14 for week two).
• Monthly by Rule: Values map to specific occurrences (e.g., 1 = Last Monday, 7 = First Monday, 14 = 2nd Last Day).

Interbank Validation Rules: The Debtor Bank is required to store this exact day in their Mandate Register. If the mandate's dateAdjustmentRule is set to 'N' (No), the Debtor Bank will strictly validate incoming collections against this day. If a collection's Action Date does not exactly match this collectionDay (or the immediately following Processing Day), the Debtor Bank will trigger an upfront rejection.

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

This dictates strict interbank validation rules for how collection amounts are calculated, capped, and adjusted over the life of the mandate.

The rules for each type are:

• FIXED: Used for contracts where an upfront, calculated Instalment Amount is the basis for normal collections. Regular collections are strictly validated and cannot exceed this Instalment Amount. The Adjustment Category for a fixed mandate must strictly be 'NEVR' (Never).
• VARIABLE: Used for contracts where an upfront Instalment Amount is calculated but can be amended by the Creditor based on pre-agreed variables, such as annual increases or interest rate changes. Regular collections cannot exceed the currently active Instalment Amount.
• USAGE_BASED: Used for contracts where the collection amount fluctuates depending on the Payer's usage of a product or service during the payment cycle. Unlike Fixed and Variable mandates, the regular Instalment Amount is optional, and interbank validation is instead performed strictly against a mandatory Maximum Collection Amount.

The Mandate Reference Number (MRN) assigned by the debtor bank upon mandate acceptance. This is the official, unique industry-wide identification number for the mandate that is unique for the mandate's entire lifecycle (including time in archives).

It is returned in the acceptance report and must be included in subsequent mandate amendment, and suspension requests.

Not to be confused with mandateIdentification (creditor's internal ID), mandateRequestTransactionIdentifier (MRTI), or mandateReference (mandate management app reference).

Structure (22 characters):

• Bank Number (4 numeric): The 4-digit identifier of the Debtor Bank.
• Mandate Creation Date (8 numeric): The date the mandate was successfully registered, formatted strictly as YYYYMMDD.
• Free Format (10 alphanumeric): A unique identifier or sequence generated by the Debtor Bank.

Mandate Request Transaction Identifier (MRTI) A unique transaction identifier used for matching multiple messages to a single transaction. This identifier is created for each new mandate request to uniquely identify the transaction within the Authenticated Collections scheme.

Important: Usage of mandateRequestTransactionIdentifier**.

• If the client is the host of the mandate register and is the source of truth for mandate state the client is required to always populate the MRTI. The format is validated and the 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.

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.