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

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"
  }
}

ZaEftDirectDebitPaymentScheme

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(ZaEftSchemeData)required
schemeData.​shortenedCreditorAccountNumberstring(ShortenedAccountNumber)= 11 characters

An account number, shortened to 11 characters according to the account number reduction rules in the EFT technical standards. This field is intended for internal use by Electrum and generally should not be populated by partner implementations.

schemeData.​shortenedDebtorAccountNumberstring(ShortenedAccountNumber)= 11 characters

An account number, shortened to 11 characters according to the account number reduction rules in the EFT technical standards. This field is intended for internal use by Electrum and generally should not be populated by partner implementations.

schemeData.​userCodestring<= 4 characters

A code allocated by PayInc. Sometimes also referred to as BankCode. May equal Installation code for in-house operation.

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

An explanation of an EFT transaction, which will be printed on the debtor's statement for direct debits or the creditor's statement for credit transfers. Note that when populating a value for a direct debit, the first 10 characters must contain the Banks user code as configured at Bankserv. If configured, Electrum will populate this value automatically, in which case at most 20 characters should be used as a reference to avoid truncation. Allowed characters are limited to printable ASCII U+0020 to U+007A (space through 'z').

{
  "schema": "ZA_RTC",
  "schemeData": {
    "shortenedCreditorAccountNumber": "stringstrin",
    "shortenedDebtorAccountNumber": "stringstrin",
    "userCode": "stri",
    "userReference": "string"
  }
}

DirectDebitPaymentScheme

Designates which scheme a direct debit is associated with and describes scheme-specific information for the direct debit.

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"
Discriminator
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_AC",
  "schemeData": {
    "creditorAbbreviatedShortName": "string",
    "creditorContractReference": "string",
    "userReference": "string"
  }
}
Copyright 2025 | Electrum Payments (Pty) Ltd