Electrum Regulated Payments Events API (17.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
Mock server

https://docs.electrumsoftware.com/_mock/openapi/elpapi/elpapi-events/

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

RequestToPayCancellationStatus

reasonInfoArray of objects(RequestToPayCancellationStatusReasonInfo)non-empty

A list of RequestToPayCancellationStatusReasonInfo values providing detailed reason information for the status.

statusstringrequired
  • CANCELLED: Cancelled - The cancellation was successfully processed and the request for payment has been cancelled.
  • REJECTED: Rejected - The cancellation was rejected. Refer to the reasonInfo for further information.
Enum"CANCELLED""REJECTED"
{
  "reasonInfo": [
    { … }
  ],
  "status": "CANCELLED"
}

RequestToPayCancellationResponse

Provides the outcome of a prior request to pay cancellation.

instructedAgentobject(InstitutionIdentification)
instructingAgentobject(InstitutionIdentification)
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.

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

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.

originalRequestToPayDataobject(OriginalRequestToPayData)

Contains key elements related to the original request to pay that is being referred to.

originalTransactionIdentifiersobject(TransactionIdentifiers)required

Holds a series of identifiers to identify the transaction or an individual message that is part of a transaction.

originalTransactionIdentifiers.​endToEndIdentificationstring<= 35 charactersrequired

Unique identification, as assigned by the initiating party, to unambiguously identify the transaction. This identification is passed on, unchanged, throughout the entire end-to-end chain. Note: this is distinct from the UETR.

originalTransactionIdentifiers.​instructionIdentificationstring<= 35 characters

Unique identification, as assigned by an instructing party for an instructed party, to unambiguously identify the instruction. The instruction identification is a point to point reference that can be used between the instructing party and the instructed party to refer to the individual instruction. It can be included in several messages related to the instruction.

originalTransactionIdentifiers.​transactionIdentificationstring<= 35 characters

Unique identification, as assigned by the first instructing agent, to unambiguously identify the transaction that is passed on, unchanged, throughout the entire interbank chain. Usage: The transaction identification can be used for reconciliation, tracking or to link tasks relating to the transaction on the interbank level. Usage: The instructing agent has to make sure that the transaction identification is unique for a pre-agreed period.

originalTransactionIdentifiers.​uetrstring(UUID)required

Universally unique identifier to provide an end-to-end reference of a payment transaction. This identifier remains the same for all messages related to the same transaction.

schemastringrequired
Value"RequestToPayCancellationResponse"
statusobject(RequestToPayCancellationStatus)required
status.​reasonInfoArray of objects(RequestToPayCancellationStatusReasonInfo)non-empty

A list of RequestToPayCancellationStatusReasonInfo values providing detailed reason information for the status.

status.​statusstringrequired
  • CANCELLED: Cancelled - The cancellation was successfully processed and the request for payment has been cancelled.
  • REJECTED: Rejected - The cancellation was rejected. Refer to the reasonInfo for further information.
Enum"CANCELLED""REJECTED"
{
  "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"
  },
  "messageIdentifiers": {
    "creationDateTime": "2019-08-24T14:15:22Z",
    "messageIdentification": "string"
  },
  "originalMessageIdentifiers": {
    "creationDateTime": "2019-08-24T14:15:22Z",
    "messageIdentification": "string"
  },
  "originalRequestToPayData": {
    "amounts": { … },
    "creditor": { … },
    "creditorAccount": { … },
    "creditorAgent": { … },
    "debtor": { … },
    "debtorAccount": { … },
    "debtorAgent": { … },
    "expiryDateTime": "2019-08-24T14:15:22Z",
    "paymentTypeInformation": { … },
    "remittanceInformation": { … },
    "requestToPayConditions": { … }
  },
  "originalTransactionIdentifiers": {
    "endToEndIdentification": "string",
    "instructionIdentification": "string",
    "transactionIdentification": "string",
    "uetr": "string"
  },
  "schema": "RequestToPayCancellationResponse",
  "status": {
    "reasonInfo": [ … ],
    "status": "CANCELLED"
  }
}

RequestToPayStatusReasonTypeCode

schemastringrequired

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

valuestringrequired
  • AB01: AbortedClearingTimeout - Clearing process aborted due to timeout.
  • AB02: AbortedClearingFatalError - Clearing process aborted due to a fatal error.
  • AB05: TimeoutCreditorAgent - Transaction stopped due to timeout at the Creditor Agent.
  • AB06: TimeoutInstructedAgent - Transaction stopped due to timeout at the Instructed Agent.
  • AB07: OfflineAgent - Agent of message is not online. Generic usage if it cannot be determined who exactly is not online.
  • AB08: OfflineCreditorAgent - Creditor Agent is not online.
  • AB09: ErrorCreditorAgent - Transaction stopped due to error at the Creditor Agent.
  • AB10: ErrorInstructedAgent - Transaction stopped due to error at the Instructed Agent.
  • AB11: TimeoutDebtorAgent - Transaction stopped due to timeout at the Debtor Agent.
  • AC04: ClosedAccountNumber - Account number specified has been closed on the bank of account's books.
  • AC05: ClosedDebtorAccountNumber - Debtor account number closed
  • AC06: BlockedAccount - Account specified is blocked, prohibiting posting of transactions against it.
  • AC07: ClosedCreditorAccountNumber - Creditor account number closed
  • AC08: InvalidBranchCode - Branch code is invalid or missing
  • AG10: AgentSuspended - Agent of message is suspended from the Real Time Payment system. Generic usage if it cannot be determined who exactly is suspended.
  • AG11: CreditorAgentSuspended - Creditor Agent of message is suspended from the Real Time Payment system.
  • AGNT: IncorrectAgent - Agent in the payment workflow is incorrect
  • AM01: ZeroAmount - Specified message amount is equal to zero
  • AM02: NotAllowedAmount - Specific transaction/message amount is greater than allowed maximum
  • AM03: NotAllowedCurrency - Specified message amount is an non processable currency outside of existing agreement
  • AM05: Duplication - Duplication
  • AM06: TooLowAmount - Specified transaction amount is less than agreed minimum.
  • AM11: InvalidTransactionCurrency - Transaction currency is invalid or missing
  • AM12: InvalidAmount - Amount is invalid or missing
  • AM13: AmountExceedsClearingSystemLimit - Transaction amount exceeds limits set by clearing system
  • AM15: AmountBelowClearingSystemMinimum - Transaction amount below minimum set by clearing system
  • AM18: InvalidNumberOfTransactions - Number of transactions is invalid or missing. Generic usage if cannot specify between group and payment information levels.
  • BE01: InconsistenWithEndCustomer - Identification of end customer is not consistent with associated account number. (formerly CreditorConsistency).
  • BE05: UnrecognisedInitiatingParty - Party who initiated the message is not recognised by the end customer
  • BE06: UnknownEndCustomer - End customer specified is not known at associated Sort/National Bank Code or does no longer exist in the books
  • BE07: MissingDebtorAddress - Specification of debtor's address, which is required for payment, is missing/not correct.
  • BE08: MissingDebtorName - Debtor name is missing
  • BE10: InvalidDebtorCountry - Debtor country code is missing or invalid
  • BE11: InvalidCreditorCountry - Creditor country code is missing or invalid
  • BE12: InvalidCountryOfResidence - Country code of residence is missing or Invalid. Generic usage if cannot specifically identify debtor or creditor
  • BE13: InvalidDebtorCountryOfResidence - Country code of debtor's residence is missing or Invalid
  • BE14: InvalidCreditorCountryOfResidence - Country code of creditor's residence is missing or Invalid
  • BE16: InvalidDebtorIdentificationCode - Debtor or Ultimate Debtor identification code missing or invalid
  • BE17: InvalidCreditorIdentificationCode - Creditor or Ultimate Creditor identification code missing or invalid
  • BE18: InvalidContactDetails - Contact details missing or invalid
  • BE19: InvalidChargeBearerCode - Charge bearer code for transaction type is invalid
  • BE20: InvalidNameLength - Name length exceeds local rules for payment type.
  • BE22: MissingCreditorName - Creditor name is missing
  • BE23: AccountProxyInvalid - Phone number or email address, or any other proxy, used as the account proxy is unknown or invalid.
  • CH03: RequestedExecutionDateOrRequestedCollectionDateTooFarInFuture - Value in Requested Execution Date or Requested Collection Date is too far in the future
  • CH04: RequestedExecutionDateOrRequestedCollectionDateTooFarInPast - Value in Requested Execution Date or Requested Collection Date is too far in the past
  • CH21: RequiredCompulsoryElementMissing - Mandatory element is missing
  • CNOR: CreditorBankIsNotRegistered - Creditor bank is not registered under this BIC in the CSM
  • CURR: IncorrectCurrency - Currency of the payment is incorrect
  • CUST: RequestedByCustomer - Cancellation requested by the Creditor
  • DS01: ElectronicSignaturesCorrect - The electronic signature(s) is/are correct
  • DS02: OrderCancelled - An authorized user has cancelled the order
  • DS04: OrderRejected - The order was rejected by the bank side (for reasons concerning content)
  • DS0G: NotAllowedPayment - Signer is not allowed to sign this operation type.
  • DS0H: NotAllowedAccount - Signer is not allowed to sign for this account.
  • DS24: WaitingTimeExpired - Waiting time expired due to incomplete order
  • DS27: UserNotYetActivated - The user is not yet activated (technically)
  • DT01: InvalidDate - Invalid date (eg, wrong or missing settlement date)
  • DT02: InvalidCreationDate - Invalid creation date and time in Group Header (eg, historic date)
  • DT03: InvalidNonProcessingDate - Invalid non bank processing date (eg, weekend or local public holiday)
  • DU01: DuplicateMessageID - Message Identification is not unique.
  • DU02: DuplicatePaymentInformationID - Payment Information Block is not unique.
  • DU03: DuplicateTransaction - Transaction is not unique.
  • DU04: DuplicateEndToEndID - End To End ID is not unique.
  • DU05: DuplicateInstructionID - Instruction ID is not unique.
  • DUPL: DuplicatePayment - Payment is a duplicate of another payment
  • FF02: SyntaxError - Syntax error reason is provided as narrative information in the additional reason information.
  • FF03: InvalidPaymentTypeInformation - Payment Type Information is missing or invalid. Generic usage if cannot specify Service Level or Local Instrument code
  • FF05: InvalidLocalInstrumentCode - Local Instrument code is missing or invalid
  • FF08: InvalidEndToEndId - End to End Id missing or invalid
  • FF10: BankSystemProcessingError - File or transaction cannot be processed due to technical issues at the bank side
  • FF11: ClearingRequestAborted - Clearing request rejected due it being subject to an abort operation.
  • MD07: EndCustomerDeceased - End customer is deceased.
  • MS02: NotSpecifiedReasonCustomerGenerated - Reason has not been specified by end customer
  • MS03: NotSpecifiedReasonAgentGenerated - Reason has not been specified by agent.
  • NARR: Narrative - Reason is provided as narrative information in the additional reason information.
  • NERI: NoERI - Credit transfer is tagged as an Extended Remittance Information (ERI) transaction but does not contain ERI.
  • RC03: InvalidDebtorBankIdentifier - Debtor bank identifier is invalid or missing
  • RC04: InvalidCreditorBankIdentifier - Creditor bank identifier is invalid or missing
  • RC06: InvalidDebtorBICIdentifier - Debtor BIC identifier is invalid or missing
  • RC07: InvalidCreditorBICIdentifier - Creditor BIC identifier is invalid or missing
  • RC09: InvalidDebtorClearingSystemMemberIdentifier - Debtor ClearingSystemMember identifier is invalid or missing
  • RC10: InvalidCreditorClearingSystemMemberIdentifier - Creditor ClearingSystemMember identifier is invalid or missing
  • RC11: InvalidIntermediaryAgent - Intermediary Agent is invalid or missing
  • RR09: InvalidStructuredCreditorReference - Structured creditor reference invalid or missing.
  • RR10: InvalidCharacterSet - Character set supplied not valid for the country and payment type.
  • S001: UETRFlaggedForCancellation - Unique End-to-end Transaction Reference (UETR) relating to a payment has been identified as being associated with a Request for Cancellation.
  • TA01: TransmissonAborted - The transmission of the file was not successful – it had to be aborted (for technical reasons)
  • NOAR: NonAgreedRTP - No existing agreement for receiving request-to-pay messages.
  • NOCM: NotCompliantGeneric - Customer account is not compliant with regulatory requirements, for example FICA (in South Africa) or any other regulatory requirements which render an account inactive for certain processing.
  • ALAC: AlreadyAcceptedRTP - Request-to-pay has already been accepted by the Debtor.
  • AEXR: AlreadyExpiredRTP - Request-to-pay Expiry Date and Time has already passed.
  • ARFR: AlreadyRefusedRTP - Request-to-pay has already been refused by the Debtor.
  • ARJR: AlreadyRejectedRTP - Request-to-pay has already been rejected.
  • EDTR: ExpiryDateTimeReached - Expiry date time of the request-to-pay is already reached.
  • EDTL: ExpiryDateTooLong - Expiry date time of the request-to-pay is too far in the future.
  • IEDT: IncorrectExpiryDateTime - Expiry date time of the request-to-pay is incorrect.
  • IRNR: InitialRTPNeverReceived - No initial request-to-pay has been received.
  • NRCH: PayerOrPayerRTPSPNotReachable - Recipient side of the request-to-pay (payer or its request-to-pay service provider) is not reachable.
  • RTNS: RTPNotSupportedForDebtor - Debtor does not support request-to-pay transactions.
  • PINS: TypeOfPaymentInstrumentNotSupported - Type of payment requested in the request-to-pay is not supported by the payer.
  • SVNR: ServiceNotRendered - The payment is cancelled since a cash amount rendered was not correct or goods or a service was not rendered to the customer, e.g. in an e-commerce situation.
  • UCRD: UnknownCreditor - Unknown Creditor.
Enum"AB01""AB02""AB05""AB06""AB07""AB08""AB09""AB10""AB11""AC04"
{
  "schema": "string",
  "value": "AB01"
}
Copyright 2025 | Electrum Payments (Pty) Ltd