EPC API for receiving Electrum calls (17.1.0)

The Electrum EPC API for receiving Electrum calls is an asynchronous API that allows Corporate Clients to participate in various nationally regulated payment schemes. This document describes the operations a Corporate Client must implement for Electrum to consume in order to complete the integration with the Electrum Enterprise Payments Channel API.

Download OpenAPI description

epc-elpapi-partner-redoc.json

epc-elpapi-partner-redoc.yaml

Overview

URL

https://electrum.co.za

Electrum Support

support@electrum.co.za

Servers

Mock server

https://docs.electrumsoftware.com/_mock/openapi/epc-cicd/epc-elpapi-partner-redoc/

Partner API sandbox

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

credit-transfer

Operations related to credit transfer transactions.

Operations

identifier-determination

Operations used to retrieve additional information related to an identifier

Operations

Schema

OriginalRequestToPayData

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

amountsobject(TransactionAmounts)

creditorobject(Party)

This model is the basic representation of a Party. It is expanded on depending on whether the party is a person or an organisation.

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)

debtorobject(Party)

This model is the basic representation of a Party. It is expanded on depending on whether the party is a person or an organisation.

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)

expiryDateTimestring(date-time)

Date and time at which the request to pay expires. Some schemes may still permit a payment after the request to pay expires. Upon expiry, the following schemes will reject an associated payment: ZA_RPP. The date must be formatted as defined by date-time in RFC3339

paymentTypeInformationobject(PaymentTypeInformation)

remittanceInformationobject(RemittanceInformation)

requestToPayConditionsobject(RequestToPayConditions)

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

{
  "amounts": {
    "bankSettlementAmount": { … },
    "instructedAmount": { … }
  },
  "creditor": {
    "address": { … },
    "contactDetails": { … },
    "countryOfResidence": "string",
    "identification": { … },
    "knownAsName": "string",
    "legalName": "string"
  },
  "creditorAccount": {
    "currency": "string",
    "identification": { … },
    "name": "string",
    "proxy": { … },
    "type": { … }
  },
  "creditorAgent": {
    "additionalIdentifications": [ … ],
    "address": { … },
    "bicfi": "string",
    "branch": { … },
    "clearingSystemMemberId": { … },
    "companyRegistration": "string",
    "lei": "string",
    "memberId": "string",
    "name": "string"
  },
  "debtor": {
    "address": { … },
    "contactDetails": { … },
    "countryOfResidence": "string",
    "identification": { … },
    "knownAsName": "string",
    "legalName": "string"
  },
  "debtorAccount": {
    "currency": "string",
    "identification": { … },
    "name": "string",
    "proxy": { … },
    "type": { … }
  },
  "debtorAgent": {
    "additionalIdentifications": [ … ],
    "address": { … },
    "bicfi": "string",
    "branch": { … },
    "clearingSystemMemberId": { … },
    "companyRegistration": "string",
    "lei": "string",
    "memberId": "string",
    "name": "string"
  },
  "expiryDateTime": "2019-08-24T14:15:22Z",
  "paymentTypeInformation": {
    "categoryPurpose": { … },
    "localInstrument": { … },
    "serviceLevel": [ … ]
  },
  "remittanceInformation": {
    "structured": [ … ],
    "unstructured": [ … ]
  },
  "requestToPayConditions": {
    "maxAmount": { … },
    "minAmount": { … }
  }
}

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

RequestToPayStatusReasonType

schemastringrequired

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

Discriminator

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": "CODE",
  "value": "AB01"
}

transactional

Operations

request-to-pay

Operations

financial

Operations

bulk

Operations

refund

Operations