An extension of BaseMessage which includes additional information pertinent to an asynchronous response message. In particular, original message identifiers.
Holds a point-to-point unique message identification string as well as a message's creation date time.
The date and time at which the message was created, in senders local timezone or UTC. The date must be formatted as defined by date-time in RFC3339
A list of key-value pairs to support adding any supplementary/additional data to an Electrum Regulated Payments API message.
Holds a point-to-point unique message identification string as well as a message's creation date time.
The date and time at which the message was created, in senders local timezone or UTC. The date must be formatted as defined by date-time in RFC3339
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).
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).
Designates which scheme a customer payment status report is associated with and describes scheme-specific information for the customer payment status report.
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.
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.
Mandate Request Transaction Identifier (MRTI) A unique transaction identifier used for matching multiple messages to a single transaction. This identifier is created for each new mandate request to uniquely identify the transaction within the Authenticated Collections scheme.
Important: Usage of mandateRequestTransactionIdentifier**.
- If the client is the host of the mandate register and is the source of truth for mandate state the client is required to always populate the
MRTI. The format is validated and the providedMRTIis used by Electrum. - If Electrum is the source of truth for mandate state the
MRTIshould not be provided by the client when initiating new mandate transactions; Electrum will generate a compliantMRTIautomatically which will be echoed back to the client.
Structure (23 characters):
- Positions 1–4 (4 numeric): Originating bank number. Must be a valid, registered bank.
- Positions 5–14 (10 alphanumeric): Origination date in the format
YYYY-MM-DD. Must be a valid date. - Positions 15–23 (9 numeric): Mandate sequence number. Unique within the bank and date.
Lifecycle behaviour:
- Mandate Initiation Request: The originating bank creates a new, unique
MRTIfor the initiation request. If not provided by the client, Electrum generates one automatically. - Mandate Amendment Request: A new, unique
MRTIis required for the amendment request. If not provided by the client, Electrum generates one automatically. The amendment is linked back to the original mandate using the Mandate Reference Number (MRN). - Mandate Cancellation Request:
- In-flight cancellation: If cancelling a mandate request that is still in-flight (e.g. awaiting debtor authentication), the
MRTImust exactly match theMRTIof the in-flight request being cancelled. If not provided, Electrum handles this automatically by retrieving theMRTIof the in-flight transaction. - Active mandate cancellation: If the mandate is already fully registered and active, a new, unique
MRTImust be issued for the cancellation request. If not provided, Electrum determines the mandate state and applies the correct rule automatically.
- In-flight cancellation: If cancelling a mandate request that is still in-flight (e.g. awaiting debtor authentication), the
- Mandate Acceptance Report: The response echoes back the
MRTIfrom the request being responded to. For API-level correlation, clients useoriginalMessageIdentifiers.messageIdentificationinstead. - Mandate Status Report: The status report echoes back the
MRTIfrom the request being reported on. For API-level correlation, clients useoriginalMessageIdentifiers.messageIdentificationinstead.
Validation rules enforced by the scheme:
- Must not be blank or spaces.
- The bank number (positions 1–4) must be a valid, registered bank.
- The date (positions 5–14) must be a valid calendar date.
- Must conform to the 23-character structured format.
- Must be unique at the time of request origination.
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.
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
suspensionRequestIdentificationin theMandateSuspensionRequest. The format is validated and the providedsuspensionRequestIdentificationis used by Electrum. - If Electrum is the source of truth for mandate state the
suspensionRequestIdentificationshould not be provided by the client when initiating new mandate suspension; Electrum will generate a compliantsuspensionRequestIdentificationautomatically 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-DDformat. - Sequence Number (9 numeric): Mandate Suspension sequence number. Must be unique within the bank and date.
APPROVED: The instruction has been approved.CANCELLED: The instruction has been cancelled.PENDING: The instruction is pending.REJECTED: The instruction has been rejected.
{ "messageIdentifiers": { "creationDateTime": "2019-08-24T14:15:22Z", "messageIdentification": "string" }, "supplementaryData": { "property1": "string", "property2": "string" }, "originalMessageIdentifiers": { "creationDateTime": "2019-08-24T14:15:22Z", "messageIdentification": "string" }, "instructedAgent": { "additionalIdentifications": [ … ], "address": { … }, "bicfi": "string", "branch": { … }, "clearingSystemMemberId": { … }, "companyRegistration": "string", "lei": "string", "memberId": "string", "name": "string" }, "instructingAgent": { "additionalIdentifications": [ … ], "address": { … }, "bicfi": "string", "branch": { … }, "clearingSystemMemberId": { … }, "companyRegistration": "string", "lei": "string", "memberId": "string", "name": "string" }, "mandateInformation": { "mandateIdentification": "string", "trackingDays": 99 }, "originalMessageNameIdentification": "string", "paymentScheme": { "schema": "ZA_RTC", "schemeData": { … } }, "schema": "CustomerPaymentStatusReport", "status": { "outcome": "APPROVED", "reasonInfo": [ … ] } }