EPC API for calling Electrum (17.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

Servers

Mock server

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

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

ZaRppDeterminationRequest

A request providing information for the lookup of a proxy or account in the context of the ZA RPP Payment Scheme:

If the identifier schema is either MOBILE or CUSTOM, proxy resolution will be performed. In this case, the identifier.namespace field is required.
If the identifier schema is GENERIC, account resolution will be performed. In this case, the accountAgent.bicfi field is required.

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.
CBPR_PLUS: Cross-Border Payments and Reporting Plus.

Enum"ZA_RTC""ZA_RPP""ZA_EFT""CBPR_PLUS"

Discriminator

accountAgentobject(InstitutionIdentification)

identifierany(ZaRppIdentifier)required

identifier.namespacestring[ 1 .. 40 ] characters

An identifier's namespace provides a context for the identifier to distinguish different identifiers which may have the same value but be intended to identify different accounts. For example, a bank may use the same MSISDN (identifier) with different namespaces to distinguish between a customer's cheque or savings accounts.

This may be used by the following schemes:

ZA_RPP

identifier.schemastringrequired

Indicates the schema of the identifier, e.g. MOBILE, CUSTOM.

Discriminator

identifier.valuestring[ 1 .. 2048 ] charactersrequired

instructedAgentobject(InstitutionIdentification)

instructingAgentobject(InstitutionIdentification)

requestorobject(ZaRppRequestor)

uetrstring(UUID)required

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

verificationIdentificationstring[ 1 .. 35 ] charactersrequired

Unique identifier for this specific verification request.

{
  "schema": "ZA_RPP",
  "accountAgent": {
    "additionalIdentifications": [ … ],
    "address": { … },
    "bicfi": "string",
    "branch": { … },
    "clearingSystemMemberId": { … },
    "companyRegistration": "string",
    "lei": "string",
    "memberId": "string",
    "name": "string"
  },
  "identifier": {
    "namespace": "string",
    "schema": "string",
    "value": "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"
  },
  "requestor": {
    "schema": "string"
  },
  "uetr": "string",
  "verificationIdentification": "string"
}

IdentifierDeterminationRequest

A model containing the foundational elements shared across messages and generally expected in a message used during processing with the Electrum Regulated Payments API.

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.

requestobject(DeterminationRequest)required

A request providing information for the lookup of a proxy or account in the context of the ZA RPP Payment Scheme:

If the identifier schema is either MOBILE or CUSTOM, proxy resolution will be performed. In this case, the identifier.namespace field is required.
If the identifier schema is GENERIC, account resolution will be performed. In this case, the accountAgent.bicfi field is required.

request.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.
CBPR_PLUS: Cross-Border Payments and Reporting Plus.

Enum"ZA_RTC""ZA_RPP""ZA_EFT""CBPR_PLUS"

Discriminator

request.accountAgentobject(InstitutionIdentification)

request.identifierany(ZaRppIdentifier)required

request.identifier.namespacestring[ 1 .. 40 ] characters

This may be used by the following schemes:

ZA_RPP

request.identifier.schemastringrequired

Indicates the schema of the identifier, e.g. MOBILE, CUSTOM.

Discriminator

request.identifier.valuestring[ 1 .. 2048 ] charactersrequired

request.instructedAgentobject(InstitutionIdentification)

request.instructingAgentobject(InstitutionIdentification)

request.requestorobject(ZaRppRequestor)

request.uetrstring(UUID)required

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

request.verificationIdentificationstring[ 1 .. 35 ] charactersrequired

Unique identifier for this specific verification request.

schemastringrequired

Value"IdentifierDeterminationRequest"

{
  "messageIdentifiers": {
    "creationDateTime": "2019-08-24T14:15:22Z",
    "messageIdentification": "string"
  },
  "supplementaryData": {
    "property1": "string",
    "property2": "string"
  },
  "request": {
    "schema": "ZA_RTC"
  },
  "schema": "IdentifierDeterminationRequest"
}

IdentifierDeterminationReport

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.
CBPR_PLUS: Cross-Border Payments and Reporting Plus.

Enum"ZA_RTC""ZA_RPP""ZA_EFT""CBPR_PLUS"

Discriminator

instructedAgentobject(InstitutionIdentification)

instructingAgentobject(InstitutionIdentification)

instructionForCreatorAgentArray of objects(CreditorAgentInstruction)>= 0 items

Further information related to the proxy resolution response, provided by the Operator, and intended for the creator agent.

originalRequestorobject(ZaRppRequestor)

originalUetrstring(UUID)required

The universally unique identifier provided in the original request as an end-to-end reference. This identifier remains the same for all messages related to the same transaction.

originalVerificationIdentificationstring[ 1 .. 35 ] charactersrequired

The request.verificationIdentification as provided in the original request.

reportInformationobject(ZaRppIdentificationReport)required

A report providing information from the lookup of a proxy in the context of the ZA RPP Payment Scheme.

This report returns information required to proceed with the clearing of funds through the use of the proxy (identifier) provided in the identifier determination request. Specifically, this report will provide the outcome of the lookup of said identifier, indication whether it is valid or not, as well as provide the name ("known as name") of the creditor, and the legal name of the creditor (both of these are mandatory in the ZA RPP Payment Scheme, despite not being mandatory in this API), namely:

accountOwner.knownAsName
accountOwner.legalName

reportInformation.accountAgentobject(InstitutionIdentification)

reportInformation.accountInformationobject(ZaRppAccountInformation)

reportInformation.accountOwnerobject(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.

reportInformation.outcomestringrequired

Enum"SUCCESSFUL""FAILED"

reportInformation.reasonCodestring[ 1 .. 4 ] characters

AB06 : Transaction stopped due to timeout at the Instructed Agent.
AB07 : Agent of message is not online. Generic usage if it cannot be determined who exactly is not online.
AB10 : An error occured at the instructed agent
AC06 : Account specified is blocked, prohibiting posting of transactions against it
AG01 : Transaction forbidden on this type of account
AG03 : Transaction type not supported/authorized on this account.
AG10 : Agent of message is suspended from the Real Time Payment system. Generic usage if it cannot be determined who exactly is suspended.
AGNT : Agent in the payment workflow is incorrect
AM02 : Specific transaction/message amount is greater than allowed maximum (e.g. payee proxy participant service limit exceeded
CH21 : Mandatory element is missing .
DT02 : Invalid creation date and time in Group Header (eg, historic date) .
DU03 : Transaction is not unique.
DUPL : Request is a duplicate of another request
FF02 : Syntax error reason is provided as narrative information in the additional reason information.
FF08 : End to End Id missing or invalid .
NAUT : Permission to be processed is not granted
NOOR : Original SCT never received
PD01 : Domain not found or invalid
PD02 : Suspended Domain provided is suspended pending investigation
BE23 : Phone number or email address, or any other proxy, used as the account proxy is unknown or invalid.
PX03 : Proxy not found in central repository
PX04 : Format of proxy invalid
RC05 : BIC identifier is invalid or missing.
RC08 : ClearingSystemMemberidentifier is invalid or missing. Generic usage if cannot specify between debit or credit account .
RR10 : Character set supplied not valid for the country and payment type.
RR12 : Invalid or missing identification required within a particular country or payment type.
RF01 : Transaction reference is not unique within the message.
AC16 : Account in Sequestration
AC17 : Account in Liquidation
AC04 : Account Closed
AC01 : Format of the account number specified is not correct
MD07 : Account Holder Deceased
NOCM : 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.
BE01 : Identification of end customer is not consistent with associated account number. (formerly CreditorConsistency).

reportInformation.transactionLimitobject(Amount)

{
  "schema": "ZA_RPP",
  "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"
  },
  "instructionForCreatorAgent": [
    { … }
  ],
  "originalRequestor": {
    "schema": "string"
  },
  "originalUetr": "string",
  "originalVerificationIdentification": "string",
  "reportInformation": {
    "accountAgent": { … },
    "accountInformation": { … },
    "accountOwner": { … },
    "outcome": "SUCCESSFUL",
    "reasonCode": "stri",
    "transactionLimit": { … }
  }
}

transactional

Operations

financial

Operations

identifier-determination

Operations

bulk

Operations

refund

Operations