Electrum Regulated Payments Events API (29.1.0)

The Electrum Regulated Payments Events API is a synchronous API that describes the events emitted by the Electrum Regulated Payments platform during the course of transaction processing.

This document describes the single endpoint that you will need to implement in order to receive event notifications posted by Electrum.

As transactions are processed by Electrum, events are emitted to provide information about the status of the transactions and the operations preformed on them. These events do not affect processing, but provide information that can be used for operational support and monitoring purposes.

All events are posted to the same single URL. Event are differentiated by a unique descriptor contained in the name field of the message body. This descriptor serves to allow the receiver to determine whether the particular event is of interest.

Download OpenAPI description
elpapi-events.json
elpapi-events.yaml
Overview
URL

https://electrum.co.za

Electrum Support

support@electrum.co.za

License

proprietary

Languages
Servers
Payments API sandbox

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

state

Transactions transition through different states. As each state is entered, an event is emitted. This event provides information about the state entered by the transaction. Included in this information is the message payload of the operation that triggered the state transition in the Electrum Regulated Payments. Note: The message payload attached to an event might be an internally-triggered message and not the message sent to or received from the Electrum Regulated Payments API.

Operations

Schema

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

mandateIdentificationstring<= 35 characters

Unique identification to unambiguously identify the mandate. This links the direct debit collection to the original mandate.

For DebiCheck, this field contains the scheme-assigned Mandate Reference Number which is the authoritative identifier for linking collections to mandates.

trackingDaysinteger[ 0 .. 99 ]

Specifies the number of days the direct debit instruction must be tracked. The debtor has this period to dispute the collection.

{
  "mandateIdentification": "string",
  "trackingDays": 99
}

ZaAcSchemeData

Scheme-specific data for Authenticated Collections (DebiCheck) direct debits. Unlike EFT, DebiCheck only supports debit transactions (collections), so shortened account numbers used for EFT file generation are not applicable here.

creditorAbbreviatedShortNamestring[ 1 .. 10 ] charactersrequired

The Creditor Abbreviated Short Name (ABSN). This is a 3 to 10 character description of the Ultimate Creditor's name, business, or product that will appear on the debtor's bank statement. This value MUST perfectly match the ABSN stored on the active Mandate Register at the Debtor Bank (i.e. must match the short name provided for the ultimateCreditor during mandate initiation). Mismatches will result in scheme rejections.

creditorContractReferencestring[ 1 .. 14 ] charactersrequired

The unique contract reference number issued by the Ultimate Creditor to the Payer/Debtor when the contract was concluded. This value MUST perfectly match the Contract Reference stored on the active Mandate Register at the Debtor Bank. (i.e must match the identifier provided for mandate.mandateRequestIdentification during mandate initiation). Mismatches will result in scheme rejections.

userReferencestring<= 140 characters^[\u0020-\u007A]*$

Under the DebiCheck scheme, the user reference expected to appear on debtor statements comprises the following:

  1. creditorAbbreviatedShortName - right-padded with spaces to exactly 10 characters (Characters 1–10)
  2. creditorContractReference - right-padded with spaces to exactly 14 characters (Characters 11–24)
  3. requestedCollectionDate (also known as cycle date) - formatted as YYMMDD (Characters 25–30)
  4. The remaining 110 characters are available for bill presentment. This text will also be captured as unstructured remittanceInformation in the DirectDebit. Only the first 30 characters are required to appear on debtor statements. Allowed characters are limited to printable characters.

This field will be provided for all inbound requests to the partner. Do NOT populate this field for outbound requests. Instead, provide any bill presentment text (up to 110 characters) in the DirectDebit model under remittanceInformation.unstructured. The engine will automatically concatenate the Creditor Short Name, Contract Reference, the DirectDebit requestedCollectionDate, and your unstructured remittance text to construct the final 140-character string required by the scheme.

{
  "creditorAbbreviatedShortName": "string",
  "creditorContractReference": "string",
  "userReference": "string"
}

ZaAcDirectDebitPaymentScheme

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.
  • TCIB: Transactions Cleared on an Immediate Basis scheme.
Enum"ZA_RTC""ZA_RPP""ZA_EFT""ZA_AC""ZA_RMS""CBPR_PLUS""TCIB"
schemeDataobject(ZaAcSchemeData)required

Scheme-specific data for Authenticated Collections (DebiCheck) direct debits. Unlike EFT, DebiCheck only supports debit transactions (collections), so shortened account numbers used for EFT file generation are not applicable here.

schemeData.​creditorAbbreviatedShortNamestring[ 1 .. 10 ] charactersrequired

The Creditor Abbreviated Short Name (ABSN). This is a 3 to 10 character description of the Ultimate Creditor's name, business, or product that will appear on the debtor's bank statement. This value MUST perfectly match the ABSN stored on the active Mandate Register at the Debtor Bank (i.e. must match the short name provided for the ultimateCreditor during mandate initiation). Mismatches will result in scheme rejections.

schemeData.​creditorContractReferencestring[ 1 .. 14 ] charactersrequired

The unique contract reference number issued by the Ultimate Creditor to the Payer/Debtor when the contract was concluded. This value MUST perfectly match the Contract Reference stored on the active Mandate Register at the Debtor Bank. (i.e must match the identifier provided for mandate.mandateRequestIdentification during mandate initiation). Mismatches will result in scheme rejections.

schemeData.​userReferencestring<= 140 characters^[\u0020-\u007A]*$

Under the DebiCheck scheme, the user reference expected to appear on debtor statements comprises the following:

  1. creditorAbbreviatedShortName - right-padded with spaces to exactly 10 characters (Characters 1–10)
  2. creditorContractReference - right-padded with spaces to exactly 14 characters (Characters 11–24)
  3. requestedCollectionDate (also known as cycle date) - formatted as YYMMDD (Characters 25–30)
  4. The remaining 110 characters are available for bill presentment. This text will also be captured as unstructured remittanceInformation in the DirectDebit. Only the first 30 characters are required to appear on debtor statements. Allowed characters are limited to printable characters.

This field will be provided for all inbound requests to the partner. Do NOT populate this field for outbound requests. Instead, provide any bill presentment text (up to 110 characters) in the DirectDebit model under remittanceInformation.unstructured. The engine will automatically concatenate the Creditor Short Name, Contract Reference, the DirectDebit requestedCollectionDate, and your unstructured remittance text to construct the final 140-character string required by the scheme.

{
  "schema": "ZA_RTC",
  "schemeData": {
    "creditorAbbreviatedShortName": "string",
    "creditorContractReference": "string",
    "userReference": "string"
  }
}
Copyright 2025 | Electrum Payments (Pty) Ltd