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:
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.
https://example.com/path/payments/api/v1/
This synchronous operation adds or updates a customer account record, when making use of Electrum account mirroring. Note that the supplied Account details object must include the Account's primaryIdentifier (which is in fact mandatory in the Account object). If the supplied primaryIdentifier is known, it will be assumed that this is an update operation. If the supplied primaryIdentifier is not known, it will be assumed that this is an insert operation.
Behaviour:
| Electrum Account Mirror as Primary source of proxy data | Electrum Account Mirror as Secondary source of proxy data | Electrum Account Mirror deactivated |
|---|---|---|
| As per description. | As per description. Note that the Electrum Account Mirror will overwrite stored information per the request sent. | Not allowed |
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.
An account within the Electrum Account mirror. Note that the primaryIdentification is permanent and immutable.
A valid, active currency code as defined in ISO 4217 indicating the currency of the amount.
Holds details pertaining to an identifier of an account or store of value.
A name or label of the account.
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.
A set of codes that describe the status of an account
Contains information detailing the owner of an account, which can be either a person or organisation.
A unique identifier used to identify this Account Owner record. This is distinct from the identification of the Account Owner, which may or may not be unique within this system, but which is typically used for identification outside of the system, such as passport numbers or national identification numbers. This identifier is used exclusively to identify the owner within this system.
Defines the type of owner.
A code to identify a country, a dependency, or another area of particular geopolitical interest, on the basis of country names obtained from the United Nations (ISO 3166, Alpha-2 code).
https://example.com/path/payments/api/v1/accounts
curl -i -X PUT \
https://example.com/path/payments/api/v1/accounts \
-H 'Content-Type: application/json' \
-H 'traceparent: string' \
-H 'tracestate: string' \
-d '{
"schema": "AccountUpdateRequest",
"messageIdentifiers": {
"messageIdentification": "8fd51c7124ba4819b9253e296a68e1da",
"creationDateTime": "2022-05-04T03:02:01Z"
},
"account": {
"type": {
"schema": "CODE",
"value": "CASH"
},
"accountName": "MyCashAccount",
"currency": "ZAR",
"openingDate": "2022-05-03T15:02:01Z",
"status": "ENABLED",
"restrictions": [
{
"restrictionType": "NO_CREDITS",
"validFrom": "2022-05-04T03:02:01Z",
"validUntil": "2022-05-05T15:02:01Z"
}
],
"primaryIdentification": {
"identifier": {
"schema": "IBAN",
"value": "GB29NWBK60161331926819"
},
"accountKnownAs": "BestAccount"
},
"additionalIdentifications": [
{
"identifier": {
"namespace": "aNamespace",
"schema": "MOBILE",
"value": "+27-0821111111"
},
"accountKnownAs": "BestAccount",
"registeredSchemes": [
"ZA_RPP"
]
}
]
},
"primaryAccountOwnerDetails": {
"schema": "INDIVIDUAL",
"recordIdentifier": 123456789,
"name": {
"title": "Mr",
"initials": "DD",
"firstName": "David",
"lastName": "Developer",
"additionalNames": "Davido",
"knownAs": "Dave"
},
"identifiers": [
{
"identification": 90001236549870,
"issuer": "Dept of Home Affairs",
"scheme": {
"schema": "CODE",
"value": "NIDN"
}
}
],
"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
]
},
"contactDetails": {
"phoneNumber": "+27-0214620000",
"mobileNumber": "+27-08230000000",
"emailAddress": "developer.dave@electrum.com"
},
"countryOfResidence": "ZA"
},
"otherAccountOwnerDetails": [
{
"schema": "ORGANISATION",
"recordIdentifier": 123456789,
"name": {
"tradingAs": "Electrum"
},
"identifiers": [
{
"schema": "BIC",
"BIC": "RY8PEG0L"
},
{
"schema": "LEI",
"LEI": "FABABA1212CDCD343400"
},
{
"schema": "OTHER",
"identification": 1234567890,
"issuer": "CIPC",
"scheme": {
"schema": "CODE",
"value": "BOID"
}
},
{
"schema": "OTHER",
"identification": 1234567890,
"issuer": "CIPC",
"scheme": {
"schema": "PROPRIETARY",
"value": "AProprietaryCode123"
}
}
],
"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
]
},
"contactDetails": {
"phoneNumber": "+27-0214620000",
"mobileNumber": "+27-08230000000",
"emailAddress": "developer.dave@electrum.com"
},
"countryOfResidence": "ZA"
}
]
}'OK. RFC9110 - 200
No contentThis synchronous operation retrieves the details of all accounts given an accountId when using the Electrum Account Mirror. The accountId is one of the unique identifiers for an account (e.g. GenericAccountIdentifier.value or MobileNumberIdentifier.value).
Behaviour:
| Electrum Account Mirror as Primary source of proxy data | Electrum Account Mirror as Secondary source of proxy data | Electrum Account Mirror deactivated |
|---|---|---|
| As per description. | As per description. | Not allowed |
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.
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:
https://example.com/path/payments/api/v1/accounts/get
curl -i -X POST \
https://example.com/path/payments/api/v1/accounts/get \
-H 'Content-Type: application/json' \
-H 'traceparent: string' \
-H 'tracestate: string' \
-d '{
"namespace": "string",
"schema": "CUSTOM",
"value": "string"
}'OK. RFC9110 - 200
An account within the Electrum Account mirror. Note that the primaryIdentification is permanent and immutable.
A valid, active currency code as defined in ISO 4217 indicating the currency of the amount.
Holds details pertaining to an identifier of an account or store of value.
A name or label of the account.
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.
A set of codes that describe the status of an account
Contains information detailing the owner of an account, which can be either a person or organisation.
A unique identifier used to identify this Account Owner record. This is distinct from the identification of the Account Owner, which may or may not be unique within this system, but which is typically used for identification outside of the system, such as passport numbers or national identification numbers. This identifier is used exclusively to identify the owner within this system.
Defines the type of owner.
A code to identify a country, a dependency, or another area of particular geopolitical interest, on the basis of country names obtained from the United Nations (ISO 3166, Alpha-2 code).
{ "account": { "type": { … }, "accountName": "MyCashAccount", "currency": "ZAR", "openingDate": "2022-05-03T15:02:01Z", "status": "ENABLED", "restrictions": [ … ], "primaryIdentification": { … }, "additionalIdentifications": [ … ] }, "primaryAccountOwnerDetails": { "schema": "INDIVIDUAL", "recordIdentifier": 123456789, "name": { … }, "identifiers": [ … ], "address": { … }, "contactDetails": { … }, "countryOfResidence": "ZA" }, "otherAccountOwnerDetails": [ { … } ] }
This synchronous operation deletes a customer account record from the Electrum account mirror. This is a permanent deletion.
Behaviour:
| Electrum Account Mirror as Primary source of proxy data | Electrum Account Mirror as Secondary source of proxy data | Electrum Account Mirror deactivated |
|---|---|---|
| As per description. | As per description. | Not allowed |
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.
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:
https://example.com/path/payments/api/v1/accounts/delete
curl -i -X POST \
https://example.com/path/payments/api/v1/accounts/delete \
-H 'Content-Type: application/json' \
-H 'traceparent: string' \
-H 'tracestate: string' \
-d '{
"namespace": "string",
"schema": "CUSTOM",
"value": "string"
}'No content. RFC9110 - 204
No contentThis synchronous operation adds an additional identifier to a customer's account record. It will not report an error if the additional identifier already exists.
Behaviour:
| Electrum Account Mirror as Primary source of proxy data | Electrum Account Mirror as Secondary source of proxy data | Electrum Account Mirror deactivated |
|---|---|---|
| Adds an additional identifier to a customer account record | Adds an additional identifier to a customer account record. | Not allowed |
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.
Holds details pertaining to an identifier of an account or store of value.
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.
Holds details pertaining to an identifier of an account or store of value.
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.
https://example.com/path/payments/api/v1/accounts/additional-identifiers
curl -i -X PUT \
https://example.com/path/payments/api/v1/accounts/additional-identifiers \
-H 'Content-Type: application/json' \
-H 'traceparent: string' \
-H 'tracestate: string' \
-d '{
"schema": "AccountAdditionalIdUpdateRequest",
"messageIdentifiers": {
"messageIdentification": "8fd51c7124ba4819b9253e296a68e1da",
"creationDateTime": "2022-05-04T03:02:01Z"
},
"currentIdentification": {
"identifier": {
"schema": "GENERIC",
"scheme": {
"schema": "CODE",
"value": "AIIN"
},
"issuer": "Amazing Bank",
"value": "1234567890"
}
},
"additionalIdentification": {
"identifier": {
"schema": "IBAN",
"value": "GB29NWBK60161331926819"
}
}
}'OK. RFC9110 - 200
No contentThis synchronous operation deletes the provided additional identifier from the Electrum account mirror. This is a permanent deletion. Note: this operation will report a failure if the provided AccountIdentifier is the only one associated with the account as this would result in an account with no identifier.
Behaviour:
| Electrum Account Mirror as Primary source of proxy data | Electrum Account Mirror as Secondary source of proxy data | Electrum Account Mirror deactivated |
|---|---|---|
| As per description. | As per description. We recommend using the PUT /accounts operation instead. | Not allowed |
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.
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:
https://example.com/path/payments/api/v1/accounts/additional-identifiers/delete
curl -i -X POST \
https://example.com/path/payments/api/v1/accounts/additional-identifiers/delete \
-H 'Content-Type: application/json' \
-H 'traceparent: string' \
-H 'tracestate: string' \
-d '{
"namespace": "string",
"schema": "CUSTOM",
"value": "string"
}'No content. RFC9110 - 204
No contentThis synchronous operation deregisters an account identifier with a specific scheme. This effectively makes it impossible to address the account externally from the scheme.
Behaviour:
| Electrum Account Mirror as Primary source of proxy data | Electrum Account Mirror as Secondary source of proxy data | Electrum Account Mirror deactivated |
|---|---|---|
| As per description. | As per description. | Not allowed |
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 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.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.
https://example.com/path/payments/api/v1/schemes/registered-identifiers/deregister
curl -i -X POST \
https://example.com/path/payments/api/v1/schemes/registered-identifiers/deregister \
-H 'Content-Type: application/json' \
-H 'traceparent: string' \
-H 'tracestate: string' \
-d '{
"schema": "IdentifierSchemeDeregistrationRequest",
"messageIdentifiers": {
"messageIdentification": "8fd51c7124ba4819b9253e296a68e1da",
"creationDateTime": "2022-05-04T03:02:01Z"
},
"uetr": "f27a34ad-c5ab-4b70-a3f9-946d743eaeaa",
"schemeDeregistration": {
"schema": "ZA_RPP",
"registeredAccountId": {
"schema": "MOBILE",
"value": "+27-0821111111"
},
"participant": {
"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
]
}
}
}
}
}'OK. RFC9110 - 200
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 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.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)
An organisation identified by a code allocated to a party as described in ISO 17442 Financial Services - Legal Entity Identifier (LEI).
Name by which an institution is known and which is usually used to identify that institution
A unique identifier assigned to a company or organisation by a duly appointed authority within a country.
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.
AB06 : TimeoutAB07 : OfflineAgentAB10 : ErrorInstructedAgentAG03 : TransactionNotSupportedAG10 : AgentSuspendedAM18 : InvalidNumberOfTransactionsCH21 : RequiredCompulsoryElementMissingDT02 : InvalidCreationDateDUPL : DuplicateRequestFF02 : SyntaxErrorNAUT : NotAuthorisedPD01 : ProxyDomainInvalidPX02 : InvalidProxyPX03 : ProxyNotFoundPX04 : ProxyFormatInvalidPX05 : Restricted ProxyPX06 : Default proxy already existsRC02 : InvalidBankIdentifierRC08 : InvalidClearingSystemMemberIdentifierRR10 : InvalidCharacterSetRR12 : InvalidPartyID{ "schema": "IdentifierSchemeDeregistrationResponse", "messageIdentifiers": { "messageIdentification": "9fd51c1234ba4819bbheyde296a68e1da", "creationDateTime": "2022-05-04T03:22:11Z" }, "originalMessageIdentifiers": { "messageIdentification": "8fd51c7124ba4819b9253e296a68e1da", "creationDateTime": "2022-05-04T03:02:01Z" }, "uetr": "f27a34ad-c5ab-4b70-a3f9-946d743eaeaa", "schemeRegistrationOutcome": { "schema": "ZA_RPP", "deregistrationStatus": "ACCEPTED", "agent": { … }, "proxy": { … } } }
This synchronous operation retrieves a set of schemes for which the provided account identifier is registered.
Behaviour:
| Electrum Account Mirror as Primary source of proxy data | Electrum Account Mirror as Secondary source of proxy data | Electrum Account Mirror deactivated |
|---|---|---|
| As per description. | As per description. | Not allowed |
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.
https://example.com/path/payments/api/v1/schemes/registered-identifiers/{registeredAccountId}
curl -i -X GET \
'https://example.com/path/payments/api/v1/schemes/registered-identifiers/{registeredAccountId}' \
-H 'traceparent: string' \
-H 'tracestate: string'OK. RFC9110 - 200
{ "registeredSchemes": [ "ZA_RPP" ] }