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 operation is synchronous.
This operation can be used to register an account identifier externally with a specific scheme (determined by the body of the operation). This effectively makes the account that is associated with the registered account identifier addressable 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. The Electrum Account Mirror will also automatically store scheme registration information for the identifier in question. | As per description. The Electrum Account Mirror will not store the scheme registration information. The client must subsequently use either the PUT /accounts or PUT /accounts/additional-identifiers to update the identifier scheme registration information within the Account Mirror. | 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.ZA_AC : South African Authenticated Collections scheme.ZA_RMS: South African Registered Mandate Service scheme.CBPR_PLUS: Cross-Border Payments and Reporting Plus.https://example.com/path/payments/api/v1/schemes/registered-identifiers/register
curl -i -X POST \
https://example.com/path/payments/api/v1/schemes/registered-identifiers/register \
-H 'Content-Type: application/json' \
-H 'traceparent: string' \
-H 'tracestate: string' \
-d '{
"schema": "IdentifierSchemeRegistrationRequest",
"messageIdentifiers": {
"messageIdentification": "8fd51c7124ba4819b9253e296a68e1da",
"creationDateTime": "2022-05-04T03:02:01Z"
},
"uetr": "f27a34ad-c5ab-4b70-a3f9-946d743eaeaa",
"schemeRegistration": {
"schema": "ZA_RPP",
"identifier": {
"namespace": "aDomain",
"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.ZA_AC : South African Authenticated Collections scheme.ZA_RMS: South African Registered Mandate Service 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": "IdentifierSchemeRegistrationResponse", "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", "registrationStatus": "ACCEPTED", "agent": { … }, "proxy": { … } } }