Electrum Regulated Payments Partner API (17.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

Mock server

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

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

Schema

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

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

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": { … }
  }
}

ZaRppAccountInformation

creationDatestring(date-time)required

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

proxyobject(NonBankingIdentifier)

traditionalAccountTypeobject(AccountType)

traditionalIdentifierobject(BankingIdentifier)required

traditionalIdentifier.issuerstring<= 35 characters

The entity that assigns the identification

traditionalIdentifier.schemastringrequired

Identifies this account identifier as generic, always GENERIC

Discriminator

traditionalIdentifier.schemeobject(GenericAccountIdentificationScheme)

Identifies the scheme that defines the identification of a generic account.

traditionalIdentifier.valuestring[ 1 .. 40 ] charactersrequired

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

operational

Operations

bulk

Operations

request-to-pay

Operations

refund

Operations

account-verification

Operations