Electrum Regulated Payments API (21.0.2)

The Electrum Regulated Payments API is an asynchronous API that allows partners 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.

As the Regulated Payments API is asynchronous, partners have a choice of how to integrate with Electrum:

Webhooks: Electrum will send events to the partner containing inbound payments to action, or responses to outbound payment requests. Webhooks are defined in this document.
Partner API: Electrum will call operations exposed by the partner containing inbound payments to action, or responses to outbound payment requests. The operations are defined in the Electrum Regulated Payments Partner API.

Receiving transactional events via webhooks or API are equivalent, except that it may be more familiar or convenient to implement one style or the other. Partners may request the method of communication Electrum should use when selecting which payment schemes to participate in.

Download OpenAPI description

elpapi-redoc.json

elpapi-redoc.yaml

Overview

URL

https://electrum.co.za

Electrum Support

support@electrum.co.za

License

proprietary

Servers

Payments API sandbox

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

transactional

Operations that participate in transaction processing, which may or may not have financial impact.

Operations

financial

Operations that participate in transaction processing and have financial impact.

Operations

credit-transfer

Operations related to credit transfer transactions.

Operations

direct-debit

Operations related to direct debit transactions.

Operations

payment-return

Operations related to payment returns.

Operations

account-management

Operations that involve customer account information.

Operations

proxy

Operations that involve the management or processing of proxies

Operations

scheme-inquiry

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

Operations

identifier-determination

Operations used to retrieve additional information related to an identifier

Operations

identifier-verification

Operations used to verify information relating to an account identifier

Operations

request-to-pay

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

Operations

funds-management

Operations related to the management of funds, including reservations, postings, and voiding of reservations.

Operations

refund

Operations related to the refund of a prior successful financial transaction.

Operations

risk-assessment

Operations related to the assessment and identification of risk in transactions.

Operations

fraud-assessment

Operations related to the processing of fraud assessments for payment transactions.

Operations

Schema

InvestigationStatus

Indicates the status of an investigation

cancellationConfirmedbooleanrequired

statusTypestringrequired

Value"CANCELLATION_CONFIRMATION"

Discriminator

{
  "cancellationConfirmed": true,
  "statusType": "CANCELLATION_CONFIRMATION"
}

ResolutionOfInvestigation

An extension of BaseMessage 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

assignmentobject(CaseAssignment)required

assignment.assigneeany(PartyInstitutionChoice)required

assignment.assignee.institutionobject(InstitutionIdentification)required

assignment.assignee.institution.additionalIdentificationsArray of objects(AccountIdentification)

assignment.assignee.institution.addressobject(PostalAddress)

assignment.assignee.institution.bicfistring^[A-Z0-9]{4,4}[A-Z]{2,2}[A-Z0-9]{2,2}([A-Z0-9...

A code allocated to a financial or non-financial institution by the ISO 9362 Registration Authority as described in ISO 9362 Banking - Banking telecommunication messages - Business identifier code (BIC)

assignment.assignee.institution.branchobject(BranchIdentification)

assignment.assignee.institution.clearingSystemMemberIdobject(ClearingSystemMemberIdentification)

assignment.assignee.institution.leistring[A-Z0-9]{18,18}[0-9]{2,2}

An organisation identified by a code allocated to a party as described in ISO 17442 Financial Services - Legal Entity Identifier (LEI).

assignment.assignee.institution.namestring<= 140 characters

Name by which an institution is known and which is usually used to identify that institution

assignment.assignee.institution.companyRegistrationstring<= 35 charactersDeprecated

A unique identifier assigned to a company or organisation by a duly appointed authority within a country.

assignment.assignee.institution.memberIdstring<= 35 charactersDeprecated

Deprecated. Please use the preferred clearingSystemMemberId.memberId instead. Identification of a member of a clearing system.

assignment.assignee.schemastringrequired

Value"INSTITUTION"

Discriminator

assignment.assignerany(PartyInstitutionChoice)required

assignment.assigner.institutionobject(InstitutionIdentification)required

assignment.assigner.institution.additionalIdentificationsArray of objects(AccountIdentification)

assignment.assigner.institution.addressobject(PostalAddress)

assignment.assigner.institution.bicfistring^[A-Z0-9]{4,4}[A-Z]{2,2}[A-Z0-9]{2,2}([A-Z0-9...

assignment.assigner.institution.branchobject(BranchIdentification)

assignment.assigner.institution.clearingSystemMemberIdobject(ClearingSystemMemberIdentification)

assignment.assigner.institution.leistring[A-Z0-9]{18,18}[0-9]{2,2}

An organisation identified by a code allocated to a party as described in ISO 17442 Financial Services - Legal Entity Identifier (LEI).

assignment.assigner.institution.namestring<= 140 characters

Name by which an institution is known and which is usually used to identify that institution

assignment.assigner.institution.companyRegistrationstring<= 35 charactersDeprecated

A unique identifier assigned to a company or organisation by a duly appointed authority within a country.

assignment.assigner.institution.memberIdstring<= 35 charactersDeprecated

Deprecated. Please use the preferred clearingSystemMemberId.memberId instead. Identification of a member of a clearing system.

assignment.assigner.schemastringrequired

Value"INSTITUTION"

Discriminator

assignment.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

assignment.identificationstring<= 35 charactersrequired

Uniquely identifies a case assignment

cancellationDetailsobject(CancellationDetails)

Specifies the details of the underlying transaction being cancelled

correctionTransactionany(CorrectiveTransactionChoice)

paymentSchemeobject(ResolutionOfInvestigationPaymentScheme)required

Designates which scheme a resolution of investigation is associated with and describes scheme-specific information.

paymentScheme.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.

Enum"ZA_RTC""ZA_RPP""ZA_EFT""ZA_AC""ZA_RMS""CBPR_PLUS"

Discriminator

resolvedCaseobject(Case6)

schemastringrequired

Value"ResolutionOfInvestigation"

statusany(InvestigationStatus)required

Indicates the status of an investigation

status.cancellationConfirmedbooleanrequired

status.statusTypestringrequired

Value"CANCELLATION_CONFIRMATION"

Discriminator

{
  "messageIdentifiers": {
    "creationDateTime": "2019-08-24T14:15:22Z",
    "messageIdentification": "string"
  },
  "supplementaryData": {
    "property1": "string",
    "property2": "string"
  },
  "originalMessageIdentifiers": {
    "creationDateTime": "2019-08-24T14:15:22Z",
    "messageIdentification": "string"
  },
  "assignment": {
    "assignee": { … },
    "assigner": { … },
    "creationDateTime": "2019-08-24T14:15:22Z",
    "identification": "string"
  },
  "cancellationDetails": {
    "cancellationStatusReasonInfo": { … },
    "originalTransaction": { … },
    "originalTransactionIdentifiers": { … },
    "transactionCancellationStatus": "RJCR"
  },
  "correctionTransaction": {
    "messageIdentifiers": { … },
    "schema": "CORRECTIVE_INTERBANK_TRANSACTION",
    "settlementAmount": { … },
    "settlementDate": "2019-08-24",
    "transactionIdentification": { … }
  },
  "paymentScheme": {
    "schema": "ZA_RTC"
  },
  "resolvedCase": {
    "creator": { … },
    "identification": "string",
    "reopenCaseIndication": true
  },
  "schema": "ResolutionOfInvestigation",
  "status": {
    "confirmationCode": "ACDA",
    "statusType": "CONFIRMATION"
  }
}

ReturnReasonTypeCode

schemastringrequired

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

valuestringrequired

AC01: IncorrectAccountNumber
AC03: InvalidCreditorAccountNumber
AC04: ClosedAccountNumber
AC06: BlockedAccount
AC13: InvalidDebtorAccountType
AC14: InvalidAgent
AC15: AccountDetailsChanged
AC16: AccountInSequestration
AC17: AccountInLiquidation
AG01: TransactionForbidden
AG02: InvalidBankOperationCode
AM01: ZeroAmount
AM02: NotAllowedAmount
AM03: NotAllowedCurrency
AM04: InsufficientFunds
AM05: Duplication
AM06: TooLowAmount
AM07: BlockedAmount
AM09: WrongAmount
AM10: InvalidControlSum
ARDT: AlreadyReturnedTransaction
BE01: InconsistenWithEndCustomer
BE04: MissingCreditorAddress
BE05: UnrecognisedInitiatingParty
BE06: UnknownEndCustomer
BE07: MissingDebtorAddress
BE08: BankError
CN01: AuthorisationCancelled
CNOR: CreditorBankIsNotRegistered
CNPC: CashNotPickedUp
CURR: IncorrectCurrency
CUST: RequestedByCustomer
DNOR: DebtorBankIsNotRegistered
DS28: ReturnForTechnicalReason
DT01: InvalidDate
DT02: ChequeExpired
ED01: CorrespondentBankNotPossible
ED03: BalanceInfoRequest
ED05: SettlementFailed
EMVL: EMVLiabilityShift
ERIN: ERIOptionNotSupported
FF05: InvalidLocalInstrumentCode
FOCR: FollowingCancellationRequest
FR01: Fraud
FRTR: FinalResponseMandateCancelled
MD01: NoMandate
MD02: MissingMandatoryInformationInMandate
MD06: RefundRequestByEndCustomer
MD07: EndCustomerDeceased
MS02: NotSpecifiedReasonCustomerGenerated
MS03: NotSpecifiedReasonAgentGenerated
NARR: Narrative
NOAS: NoAnswerFromCustomer
NOCM: NotCompliant
NOOR: NoOriginalTransactionReceived
PINL: PINLiabilityShift
RC01: BankIdentifierIncorrect
RC07: InvalidCreditorBICIdentifier
RF01: NotUniqueTransactionReference
RR01: MissingDebtorAccountOrIdentification
RR02: MissingDebtorNameOrAddress
RR03: MissingCreditorNameOrAddress
RR04: RegulatoryReason
RUTA: ReturnUponUnableToApply
SL01: SpecificServiceOfferedByDebtorAgent
SL02: SpecificServiceOfferedByCreditorAgent
SL11: CreditorNotOnWhitelistOfDebtor
SL12: CreditorOnBlacklistOfDebtor
SL13: MaximumNumberOfDirectDebitTransactionsExceeded
SL14: MaximumDirectDebitTransactionAmountExceeded
SP01: PaymentStopped
SP02: PreviouslyStopped
SVNR: ServiceNotRendered
TM01: CutOffTime
TRAC: RemovedFromTracking
UPAY: UnduePayment
AGNT: IncorrectAgent
FF06: InvalidCategoryPurposeCode
RC08: InvalidClearingSystemMemberIdentifier
BE11: InvalidCreditorCountry
BE17: InvalidCreditorIdentificationCode
AC02: InvalidDebtorAccountNumber
RR11: InvalidDebtorAgentServiceIdentification
BE10: InvalidDebtorCountry
BE16: InvalidDebtorIdentificationCode
RC11: InvalidIntermediaryAgent
RR12: InvalidPartyIdentification
FF03: InvalidPaymentTypeInformation
FF07: InvalidPurpose
FF04: InvalidServiceLevelCode
RR09: InvalidStructuredCreditorReference
RR05: RegulatoryInformationInvalid
RR07: RemittanceInformationInvalid
RR08: RemittanceInformationTruncated
RR06: TaxInformationInvalid
AG07: UnsuccesfulDirectDebit
G004: CreditPendingFunds
MD05: CollectionNotDue
AC07: ClosedCreditorAccountNumber

Enum"AC01""AC03""AC04""AC06""AC13""AC14""AC15""AC16""AC17""AG01"

{
  "schema": "string",
  "value": "AC01"
}

operational

Operations

bulk

Operations

accounts

Operations

account-verification

Operations