EPC API for calling Electrum (18.1.0)

The Electrum EPC API for calling Electrum is an asynchronous API that allows Corporate Clients to participate in various nationally regulated payment schemes This document describes the operations exposed by Electrum for partners to consume in order to initiate outbound or respond to inbound payments.

Download OpenAPI description
epc-elpapi-redoc.json
epc-elpapi-redoc.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/api/v1/

credit-transfer

Operations related to credit transfer transactions.

Operations

scheme-inquiry

Operations that are related to retrieving information from industry for a particular scheme.

Operations

request-to-pay

Operations which pertain to a request for payment from a creditor to a debtor

Operations

Schema

RequestToPayStatusReasonInfo

Provides detailed information on a status reason.

additionalInformationstring

A human friendly description of the status reason including any further details if applicable.

reasonobject(RequestToPayStatusReasonType)required
reason.​schemastringrequired

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

Discriminator
reason.​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"
{
  "additionalInformation": "string",
  "reason": {
    "schema": "string",
    "value": "AB01"
  }
}

RequestToPayStatus

reasonInfoArray of objects(RequestToPayStatusReasonInfo)non-empty

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

statusstringrequired
  • PAID: Paid - The request to pay was approved by the debtor and the payment has been processed. Note that the outcome of the payment itself is not communicated.
  • ACCEPTED: Accepted - The request to pay was approved by the debtor but the payment has not yet been processed.
  • CANCELLED: Cancelled - Request to pay has been successfully cancelled after having received a request for cancellation.
  • EXPIRED: Expired - The request to pay has expired.
  • PENDING: Pending - The request to pay has been forwarded and an intial status report is still expected.
  • PRESENTED: Presented - The request to pay has been accepted by the payer participant and will be presented to the debtor.
  • REJECTED: Rejected - The request to pay has been rejected.
  • REFUND_IN_PROGRESS: Refund in progress - The refund of the original request to pay is currently in progress and does not yet have an outcome
  • REFUNDED: Refunded - The refund of the original request to pay has been completed successfully
Enum"PAID""ACCEPTED""CANCELLED""EXPIRED""PENDING""PRESENTED""REJECTED""REFUND_IN_PROGRESS""REFUNDED"
{
  "reasonInfo": [
    { … }
  ],
  "status": "PAID"
}

RequestToPayResponse

An extension of BaseTransactionMessage which includes additional information pertinent to an asynchronous response message. In particular, original message identifiers.

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.

supplementaryDataobject(SupplementaryData)

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

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.

transactionIdentifiersobject(TransactionIdentifiers)required

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

transactionIdentifiers.​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.

transactionIdentifiers.​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.

transactionIdentifiers.​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.

transactionIdentifiers.​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.

instructedAgentobject(InstitutionIdentification)
instructingAgentobject(InstitutionIdentification)
originalRequestToPayDataobject(OriginalRequestToPayData)

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

requestToPayConditionsobject(RequestToPayConditions)

Describes the various aspects of a request to pay which must be accepted or to what extent they may be altered.

schemastringrequired
Value"RequestToPayResponse"
statusobject(RequestToPayStatus)required
status.​reasonInfoArray of objects(RequestToPayStatusReasonInfo)non-empty

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

status.​statusstringrequired
  • PAID: Paid - The request to pay was approved by the debtor and the payment has been processed. Note that the outcome of the payment itself is not communicated.
  • ACCEPTED: Accepted - The request to pay was approved by the debtor but the payment has not yet been processed.
  • CANCELLED: Cancelled - Request to pay has been successfully cancelled after having received a request for cancellation.
  • EXPIRED: Expired - The request to pay has expired.
  • PENDING: Pending - The request to pay has been forwarded and an intial status report is still expected.
  • PRESENTED: Presented - The request to pay has been accepted by the payer participant and will be presented to the debtor.
  • REJECTED: Rejected - The request to pay has been rejected.
  • REFUND_IN_PROGRESS: Refund in progress - The refund of the original request to pay is currently in progress and does not yet have an outcome
  • REFUNDED: Refunded - The refund of the original request to pay has been completed successfully
Enum"PAID""ACCEPTED""CANCELLED""EXPIRED""PENDING""PRESENTED""REJECTED""REFUND_IN_PROGRESS""REFUNDED"
{
  "messageIdentifiers": {
    "creationDateTime": "2019-08-24T14:15:22Z",
    "messageIdentification": "string"
  },
  "supplementaryData": {
    "property1": "string",
    "property2": "string"
  },
  "originalMessageIdentifiers": {
    "creationDateTime": "2019-08-24T14:15:22Z",
    "messageIdentification": "string"
  },
  "transactionIdentifiers": {
    "endToEndIdentification": "string",
    "instructionIdentification": "string",
    "transactionIdentification": "string",
    "uetr": "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"
  },
  "originalRequestToPayData": {
    "amounts": { … },
    "creditor": { … },
    "creditorAccount": { … },
    "creditorAgent": { … },
    "debtor": { … },
    "debtorAccount": { … },
    "debtorAgent": { … },
    "expiryDateTime": "2019-08-24T14:15:22Z",
    "paymentTypeInformation": { … },
    "remittanceInformation": { … },
    "requestToPayConditions": { … }
  },
  "requestToPayConditions": {
    "maxAmount": { … },
    "minAmount": { … }
  },
  "schema": "RequestToPayResponse",
  "status": {
    "reasonInfo": [ … ],
    "status": "PAID"
  }
}

transactional

Operations

financial

Operations

identifier-determination

Operations

bulk

Operations

refund

Operations
Copyright 2025 | Electrum Payments (Pty) Ltd