Electrum Regulated Payments Partner API (18.1.0)

The Electrum Regulated Payments API is an asynchronous API that allows partners to participate in various nationally regulated payment schemes.

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 the Electrum Regulated Payments Partner API.
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 this document.

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.

This document describes the operations a partner must implement for Electrum to consume in order to complete the integration with the Electrum Regulated Payments API.

Download OpenAPI description

elpapi-partner.json

elpapi-partner.yaml

Overview

URL

https://electrum.co.za

Electrum Support

support@electrum.co.za

Servers

Partner API sandbox

https://example.com/path/payments/partner-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

identifier-determination

Operations used to retrieve additional information related to an identifier

Operations

funds-management

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

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

ZaRppAccountInformation

creationDatestring(date-time)required

The date when the account referenced by this proxy identifier was created.

proxyobject(NonBankingIdentifier)

traditionalAccountTypeobject(AccountType)

traditionalIdentifierobject(BankingIdentifier)

{
  "creationDate": "2019-08-24T14:15:22Z",
  "proxy": {
    "namespace": "string",
    "schema": "string"
  },
  "traditionalAccountType": {
    "schema": "string",
    "value": "CACC"
  },
  "traditionalIdentifier": {
    "schema": "string",
    "value": "string"
  }
}

ZaRppIdentificationReport

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

accountAgentobject(InstitutionIdentification)

accountInformationobject(ZaRppAccountInformation)

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.

outcomestringrequired

Enum"SUCCESSFUL""FAILED"

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

reasonDescriptionstring

A description of the reason that the identification request failed.

transactionLimitobject(Amount)

{
  "accountAgent": {
    "additionalIdentifications": [ … ],
    "address": { … },
    "bicfi": "string",
    "branch": { … },
    "clearingSystemMemberId": { … },
    "companyRegistration": "string",
    "lei": "string",
    "memberId": "string",
    "name": "string"
  },
  "accountInformation": {
    "creationDate": "2019-08-24T14:15:22Z",
    "proxy": { … },
    "traditionalAccountType": { … },
    "traditionalIdentifier": { … }
  },
  "accountOwner": {
    "address": { … },
    "contactDetails": { … },
    "countryOfResidence": "string",
    "identification": { … },
    "knownAsName": "string",
    "legalName": "string"
  },
  "outcome": "SUCCESSFUL",
  "reasonCode": "stri",
  "reasonDescription": "string",
  "transactionLimit": {
    "currency": "string",
    "value": 0.1
  }
}

ZaRppIdentifierDeterminationReport

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.

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

A description of the reason that the identification request failed.

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",
    "reasonDescription": "string",
    "transactionLimit": { … }
  }
}

operational

Operations

bulk

Operations

request-to-pay

Operations

refund

Operations

account-verification

Operations