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.
This operation is asynchronous. The outcome of the request is delivered by the outboundIdentifierDeterminationReport operation.
The outbound identifier determination operation can be called to resolve additional information about an identifier, for example to resolve a proxy.
In the context of an outbound payment, a partner sends Electrum an identifier determination inquiry. Electrum then performs whatever routing, orchestration and protocol translation is necessary to fulfil the request with the correct upstream party.
| Scheme | Applicable | Function Enabled |
|---|---|---|
| ZA_EFT | ✗ | N/A |
| ZA_RPP | ✓ | Proxy Resolution - Validate a proxy and return additional information for use in a subsequent credit transfer |
| ZA_RTC | ✗ | N/A |
A value used to trace an HTTP message within an Electrum Regulated Payments implementation. This field must be set as per the traceparent element defined in the W3C Trace Context Level 2 specification.
A value used to provide context to an HTTP message as it is traced within an Electrum Regulated Payments implementation. This field must be set as per the traceparent element defined in the W3C Trace Context Level 2 specification.
Holds a point-to-point unique message identification string as well as a message's creation date time.
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
A list of key-value pairs to support adding any supplementary/additional data to an Electrum Regulated Payments API message.
Identifies the scheme used for the payment
ZA_RTC: South African Realtime Clearing schemeZA_RPP: South African Realtime Payments Platform scheme.ZA_EFT: South African Electronic Funds Transfer scheme.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:
Indicates the schema of the identifier, e.g. MOBILE, CUSTOM.
Universally unique identifier to provide an end-to-end reference. This identifier remains the same for all messages related to the same transaction.
curl -i -X POST \
https://docs.electrumsoftware.com/_mock/openapi/epc/bpp-elpapi/identifiers/outbound/identifier-determination \
-H 'Content-Type: application/json' \
-H 'traceparent: string' \
-H 'tracestate: string' \
-d '{
"messageIdentifiers": {
"messageIdentification": "8fd51c7124ba4819b9253e296a68e1da",
"creationDateTime": "2022-05-04T03:02:01Z"
},
"schema": "IdentifierDeterminationRequest",
"request": {
"schema": "ZA_RPP",
"instructedAgent": {
"bicfi": "RY8PEG0L",
"memberId": "AmazingBankId",
"name": "Amazing Bank Inc",
"branch": {
"identification": 210514,
"name": "ABC Plettenberg Bay",
"address": {
"addressType": "ADDR",
"department": "Department of Mysteries",
"streetName": "Street of Mysteries",
"buildingNumber": 42,
"buildingName": "Mysterious Building",
"floor": 42,
"postBox": 1024,
"postCode": 4242,
"townName": "Mysty Town",
"townLocationName": "Mysty Location",
"districtName": "Mysty District",
"countrySubDivision": "Mysterious Cape",
"country": "ZA",
"addressLine": [
"16A",
"New market street",
"Foreshore",
"Cape Town",
"ZA",
8001
]
}
}
},
"instructingAgent": {
"bicfi": "RY8PEG0L",
"memberId": "AmazingBankId",
"name": "Amazing Bank Inc",
"branch": {
"identification": 210514,
"name": "ABC Plettenberg Bay",
"address": {
"addressType": "ADDR",
"department": "Department of Mysteries",
"streetName": "Street of Mysteries",
"buildingNumber": 42,
"buildingName": "Mysterious Building",
"floor": 42,
"postBox": 1024,
"postCode": 4242,
"townName": "Mysty Town",
"townLocationName": "Mysty Location",
"districtName": "Mysty District",
"countrySubDivision": "Mysterious Cape",
"country": "ZA",
"addressLine": [
"16A",
"New market street",
"Foreshore",
"Cape Town",
"ZA",
8001
]
}
}
},
"requestor": {
"schema": "INSTITUTION_IDENTIFICATION",
"bicfi": "RY8PEG0L",
"memberId": "AmazingBankId",
"domain": "ADomain",
"name": "Amazing Bank Inc"
},
"identifier": {
"namespace": "AnotherDomain",
"schema": "MOBILE",
"value": "+27-0214620000"
},
"uetr": "f27a34ad-c5ab-4b70-a3f9-946d743eaeaa",
"verificationIdentification": "e3360de097fe42a195cc53251d0ec839"
},
"supplementaryData": {
"customData1": "My custom data 1",
"customData2": "My custom data 2"
}
}'Accepted. RFC9110 - 202
No contentThis operation is synchronous.
The outbound identifier determination operation can be called to resolve additional information about an identifier, for example to resolve a proxy.
In the context of an outbound payment, a partner sends Electrum an identifier determination inquiry. Electrum then performs whatever routing, orchestration and protocol translation is necessary to fulfil the request with the correct upstream party.
| Scheme | Applicable | Function Enabled |
|---|---|---|
| ZA_EFT | ✗ | N/A |
| ZA_RPP | ✓ | Proxy Resolution - Validate a proxy and return additional information for use in a subsequent credit transfer |
| ZA_RTC | ✗ | N/A |
A value used to trace an HTTP message within an Electrum Regulated Payments implementation. This field must be set as per the traceparent element defined in the W3C Trace Context Level 2 specification.
A value used to provide context to an HTTP message as it is traced within an Electrum Regulated Payments implementation. This field must be set as per the traceparent element defined in the W3C Trace Context Level 2 specification.
Holds a point-to-point unique message identification string as well as a message's creation date time.
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
A list of key-value pairs to support adding any supplementary/additional data to an Electrum Regulated Payments API message.
Identifies the scheme used for the payment
ZA_RTC: South African Realtime Clearing schemeZA_RPP: South African Realtime Payments Platform scheme.ZA_EFT: South African Electronic Funds Transfer scheme.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:
Indicates the schema of the identifier, e.g. MOBILE, CUSTOM.
Universally unique identifier to provide an end-to-end reference. This identifier remains the same for all messages related to the same transaction.
curl -i -X POST \
https://docs.electrumsoftware.com/_mock/openapi/epc/bpp-elpapi/identifiers/outbound/identifier-determination-sync \
-H 'Content-Type: application/json' \
-H 'traceparent: string' \
-H 'tracestate: string' \
-d '{
"messageIdentifiers": {
"messageIdentification": "8fd51c7124ba4819b9253e296a68e1da",
"creationDateTime": "2022-05-04T03:02:01Z"
},
"schema": "IdentifierDeterminationRequest",
"request": {
"schema": "ZA_RPP",
"instructedAgent": {
"bicfi": "RY8PEG0L",
"memberId": "AmazingBankId",
"name": "Amazing Bank Inc",
"branch": {
"identification": 210514,
"name": "ABC Plettenberg Bay",
"address": {
"addressType": "ADDR",
"department": "Department of Mysteries",
"streetName": "Street of Mysteries",
"buildingNumber": 42,
"buildingName": "Mysterious Building",
"floor": 42,
"postBox": 1024,
"postCode": 4242,
"townName": "Mysty Town",
"townLocationName": "Mysty Location",
"districtName": "Mysty District",
"countrySubDivision": "Mysterious Cape",
"country": "ZA",
"addressLine": [
"16A",
"New market street",
"Foreshore",
"Cape Town",
"ZA",
8001
]
}
}
},
"instructingAgent": {
"bicfi": "RY8PEG0L",
"memberId": "AmazingBankId",
"name": "Amazing Bank Inc",
"branch": {
"identification": 210514,
"name": "ABC Plettenberg Bay",
"address": {
"addressType": "ADDR",
"department": "Department of Mysteries",
"streetName": "Street of Mysteries",
"buildingNumber": 42,
"buildingName": "Mysterious Building",
"floor": 42,
"postBox": 1024,
"postCode": 4242,
"townName": "Mysty Town",
"townLocationName": "Mysty Location",
"districtName": "Mysty District",
"countrySubDivision": "Mysterious Cape",
"country": "ZA",
"addressLine": [
"16A",
"New market street",
"Foreshore",
"Cape Town",
"ZA",
8001
]
}
}
},
"requestor": {
"schema": "INSTITUTION_IDENTIFICATION",
"bicfi": "RY8PEG0L",
"memberId": "AmazingBankId",
"domain": "ADomain",
"name": "Amazing Bank Inc"
},
"identifier": {
"namespace": "AnotherDomain",
"schema": "MOBILE",
"value": "+27-0214620000"
},
"uetr": "f27a34ad-c5ab-4b70-a3f9-946d743eaeaa",
"verificationIdentification": "e3360de097fe42a195cc53251d0ec839"
},
"supplementaryData": {
"customData1": "My custom data 1",
"customData2": "My custom data 2"
}
}'OK. RFC9110 - 200
Note that a response containing a 200 (OK) HTTP status does not necessarily mean that the response contains a positive outcome but rather that Electrum successfully processed the request and is providing a response. The functional outcome might still be a negative one (e.g. the identifier was not found). In the event that Electrum encounters a technical error when processing the request, the appropriate 4xx or 5xx response will be used.
Holds a point-to-point unique message identification string as well as a message's creation date time.
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
A list of key-value pairs to support adding any supplementary/additional data to an Electrum Regulated Payments API message.
Holds a point-to-point unique message identification string as well as a message's creation date time.
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
Identifies the scheme used for the payment
ZA_RTC: South African Realtime Clearing schemeZA_RPP: South African Realtime Payments Platform scheme.ZA_EFT: South African Electronic Funds Transfer scheme.Further information related to the proxy resolution response, provided by the Operator, and intended for the creator agent.
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.
The request.verificationIdentification as provided in the original request.
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.knownAsNameaccountOwner.legalNameThis model is the basic representation of a Party. It is expanded on depending on whether the party is a person or an organisation.
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 agentAC06 : Account specified is blocked, prohibiting posting of transactions against itAG01 : Transaction forbidden on this type of accountAG03 : 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 incorrectAM02 : Specific transaction/message amount is greater than allowed maximum (e.g. payee proxy participant service limit exceededCH21 : 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 requestFF02 : 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 grantedNOOR : Original SCT never receivedPD01 : Domain not found or invalidPD02 : Suspended Domain provided is suspended pending investigationBE23 : Phone number or email address, or any other proxy, used as the account proxy is unknown or invalid.PX03 : Proxy not found in central repositoryPX04 : Format of proxy invalidRC05 : 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 SequestrationAC17 : Account in LiquidationAC04 : Account ClosedAC01 : Format of the account number specified is not correctMD07 : Account Holder DeceasedNOCM : 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).{ "schema": "IdentifierDeterminationResponse", "messageIdentifiers": { "messageIdentification": "9fd51c1234ba4819bbheyde296a68e1da", "creationDateTime": "2022-05-04T03:22:11Z" }, "originalMessageIdentifiers": { "messageIdentification": "8fd51c7124ba4819b9253e296a68e1da", "creationDateTime": "2022-05-04T03:02:01Z" }, "report": { "originalUetr": "f27a34ad-c5ab-4b70-a3f9-946d743eaeaa", "originalVerificationIdentification": "1001", "schema": "ZA_RPP", "reportInformation": { … }, "instructedAgent": { … }, "instructingAgent": { … }, "originalRequestor": { … } }, "supplementaryData": { "customData1": "My custom data 1", "customData2": "My custom data 2" } }