Electrum Regulated Payments Events API (26.1.1)

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
Overview
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

BaseOriginalTransactionData

amountsobject(TransactionAmounts)
creditorAccountobject(PaymentAccount)

Representation of an account for payment purposes. Note that at least one of identification or proxy is expected to be present.

creditorAgentobject(InstitutionIdentification)
creditorAgentAccountobject(PaymentAccount)

Representation of an account for payment purposes. Note that at least one of identification or proxy is expected to be present.

debtorAccountobject(PaymentAccount)

Representation of an account for payment purposes. Note that at least one of identification or proxy is expected to be present.

debtorAgentobject(InstitutionIdentification)
debtorAgentAccountobject(PaymentAccount)

Representation of an account for payment purposes. Note that at least one of identification or proxy is expected to be present.

paymentMethodstring(PaymentMethod)
  • CreditTransfer - Transfer of an amount of money in the books of the account servicer.
  • DirectDebit - Collection of an amount of money from the debtor's account by the creditor, the amount and date of collection may vary.
Enum"CreditTransfer""DirectDebit"
paymentTypeInformationobject(PaymentTypeInformation)
purposeobject(PurposeType)

Specifies the underlying reason for the payment transaction

remittanceInformationobject(RemittanceInformation)
settlementDatestring(date)

Date on which the amount of money ceases to be available to the agent that owes it and when the amount of money becomes available to the agent to which it is due.

supplementaryDataobject(SupplementaryData)

A list of key-value pairs to support adding any supplementary/additional data to an Electrum Regulated Payments API message.

{ "amounts": { "bankSettlementAmount": {}, "instructedAmount": {} }, "creditorAccount": { "currency": "string", "identification": {}, "name": "string", "proxy": {}, "type": {} }, "creditorAgent": { "additionalIdentifications": [], "address": {}, "bicfi": "string", "branch": {}, "clearingSystemMemberId": {}, "companyRegistration": "string", "lei": "string", "memberId": "string", "name": "string" }, "creditorAgentAccount": { "currency": "string", "identification": {}, "name": "string", "proxy": {}, "type": {} }, "debtorAccount": { "currency": "string", "identification": {}, "name": "string", "proxy": {}, "type": {} }, "debtorAgent": { "additionalIdentifications": [], "address": {}, "bicfi": "string", "branch": {}, "clearingSystemMemberId": {}, "companyRegistration": "string", "lei": "string", "memberId": "string", "name": "string" }, "debtorAgentAccount": { "currency": "string", "identification": {}, "name": "string", "proxy": {}, "type": {} }, "paymentMethod": "CreditTransfer", "paymentTypeInformation": { "categoryPurpose": {}, "localInstrument": {}, "serviceLevel": [] }, "purpose": { "schema": "string", "value": "BKDF" }, "remittanceInformation": { "structured": [], "unstructured": [] }, "settlementDate": "2019-08-24", "supplementaryData": { "property1": "string", "property2": "string" } }

OriginalTransactionReference

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

amountsobject(TransactionAmounts)
creditorAccountobject(PaymentAccount)

Representation of an account for payment purposes. Note that at least one of identification or proxy is expected to be present.

creditorAgentobject(InstitutionIdentification)
creditorAgentAccountobject(PaymentAccount)

Representation of an account for payment purposes. Note that at least one of identification or proxy is expected to be present.

debtorAccountobject(PaymentAccount)

Representation of an account for payment purposes. Note that at least one of identification or proxy is expected to be present.

debtorAgentobject(InstitutionIdentification)
debtorAgentAccountobject(PaymentAccount)

Representation of an account for payment purposes. Note that at least one of identification or proxy is expected to be present.

paymentMethodstring(PaymentMethod)
  • CreditTransfer - Transfer of an amount of money in the books of the account servicer.
  • DirectDebit - Collection of an amount of money from the debtor's account by the creditor, the amount and date of collection may vary.
Enum"CreditTransfer""DirectDebit"
paymentTypeInformationobject(PaymentTypeInformation)
purposeobject(PurposeType)

Specifies the underlying reason for the payment transaction

remittanceInformationobject(RemittanceInformation)
settlementDatestring(date)

Date on which the amount of money ceases to be available to the agent that owes it and when the amount of money becomes available to the agent to which it is due.

supplementaryDataobject(SupplementaryData)

A list of key-value pairs to support adding any supplementary/additional data to an Electrum Regulated Payments API message.

creditorany(PartyInstitutionChoice)
debtorany(PartyInstitutionChoice)
mandateInformationobject(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).

{ "amounts": { "bankSettlementAmount": {}, "instructedAmount": {} }, "creditorAccount": { "currency": "string", "identification": {}, "name": "string", "proxy": {}, "type": {} }, "creditorAgent": { "additionalIdentifications": [], "address": {}, "bicfi": "string", "branch": {}, "clearingSystemMemberId": {}, "companyRegistration": "string", "lei": "string", "memberId": "string", "name": "string" }, "creditorAgentAccount": { "currency": "string", "identification": {}, "name": "string", "proxy": {}, "type": {} }, "debtorAccount": { "currency": "string", "identification": {}, "name": "string", "proxy": {}, "type": {} }, "debtorAgent": { "additionalIdentifications": [], "address": {}, "bicfi": "string", "branch": {}, "clearingSystemMemberId": {}, "companyRegistration": "string", "lei": "string", "memberId": "string", "name": "string" }, "debtorAgentAccount": { "currency": "string", "identification": {}, "name": "string", "proxy": {}, "type": {} }, "paymentMethod": "CreditTransfer", "paymentTypeInformation": { "categoryPurpose": {}, "localInstrument": {}, "serviceLevel": [] }, "purpose": { "schema": "string", "value": "BKDF" }, "remittanceInformation": { "structured": [], "unstructured": [] }, "settlementDate": "2019-08-24", "supplementaryData": { "property1": "string", "property2": "string" }, "creditor": { "party": {}, "schema": "PARTY" }, "debtor": { "party": {}, "schema": "PARTY" }, "mandateInformation": { "mandateIdentification": "string", "trackingDays": 99 } }

CancellationReasonCode

schemastring

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

valuestring

AC02 InvalidDebtorAccountNumber - Debtor account number invalid or missing. AC03 InvalidCreditorAccountNumber - Wrong account number in Credit Transfer. AGNT IncorrectAgent - Agent in the payment workflow is incorrect. AM09 WrongAmount - Amount is not the amount agreed or expected. BE16 InvalidDebtorIdentificationCode - Debtor or Ultimate Debtor identification code missing or invalid. COVR CoverCancelledOrReturned - Cover payments has either been returned or cancelled. CURR IncorrectCurrency - Currency of the payment is incorrect. CUST RequestedByCustomer - Cancellation requested by the Debtor. CUTA CancelUponUnableToApply - Cancellation requested because an investigation request has been received and no remediation is possible. DS24 TimeOut - Cancellation requested because the original payment order expired due to time-out. DT01 InvalidDate - Invalid date (for example, wrong or missing settlement date). DUPL DuplicatePayment - Payment is a duplicate of another payment. FRAD FraudulentOrigin - Cancellation requested following a transaction that was originated fraudulently. The use of the FraudulentOrigin code should be governed by jurisdictions. FRNA ForwardToNextAgent - To complement a rejection response, suggesting the request for cancelation should be forwarded to the next agent in the payment transaction chain. FRTR FinalResponse - Direct Debit Tracking recalled as Mandate Cancelled INDM IndemnityRequired - To express the wish to establish a bilateral indemnity agreement. MODT ModifiedTransaction - The underlying transaction in relation to an RTP was modified. PAID TransactionAlreadyPaid - The underlying transaction in relation to an RTP was already paid (via other means). 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. SYAD RequestToSettlementSystemAdministrator - Cancellation requested by System Member to Settlement System Administrator to indicate that the cancellation request must not be forwarded further in the chain. TECH TechnicalProblem - Cancellation requested following technical problems resulting in an erroneous transaction. UPAY UnduePayment - Payment is not justified. ENUE EndUserError - Cancellation or request for return requested by the Debtor specifically due to one or more errors by debtor in the original Credit Transfer. Usage: This code can be used for any error in the original Credit Transfer made by the Debtor. Can also be used if multiple errors were made in the original Credit Transfer. UAPA UnauthorizedPayment - "The Debtor is requesting a return of the payment because the payment was not properly authorized. Usage: This code can be used in the case where a Credit Transfer was made without proper authorization from the Debtor. This could be due to compromised end user credentials." NARR Narrative - Reason is provided as narrative information in the additional reason information. INCR InvalidCancellationRequest - Process a cancellation request with incorrect reference to original batch. BIAS BatchInstructionAlreadySettled - Process a cancellation request but batch already settled. DRTP DuplicationRequestToPay - Duplication of a request-to-pay message. WNTB WarrantyBreach - Breach of warranty provided in connection with a request for payment. MD06 RefundRequestByEndCustomer - Return of funds requested by end customer. PPRC PayeeParticipantRTPCancellation - Request to Pay cancellation initiated because the Payee is not in good standing. ECAG ErrorCreditorAgent - Payee (Creditor) cancels the Request To Pay (RTP) request due to error or adjustment agreement with Payer/Debtor. NFNA NeverForwardToNextAgent - To complement a cancellation request, instructing the market infrastructure that the request for cancelation should not be forwarded to the next agent in the payment transaction chain.

Enum"AC02""AC03""AGNT""AM09""BE16""COVR""CURR""CUST""CUTA""DS24"
{ "schema": "string", "value": "AC02" }