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:
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.
https://example.com/path/payments/partner-api/v1/
Provides details about whether and how a debit may be disputed by the debtor. This model encapsulates dispute eligibility metadata which can be passed through pacs.003 payloads to downstream systems.
Reason codes indicating why the debit may or may not be disputed by the debtor.
{ "disputable": true, "disputableReasons": [ { … } ], "disputePeriodDays": 0 }
Scheme-specific data for Authenticated Collections (DebiCheck) direct debits. Unlike EFT, DebiCheck only supports debit transactions (collections), so shortened account numbers used for EFT file generation are not applicable here.
The Creditor Abbreviated Short Name (ABSN). This is a 3 to 10 character description of the Ultimate Creditor's name, business, or product that will appear on the debtor's bank statement. This value MUST perfectly match the ABSN stored on the active Mandate Register at the Debtor Bank (i.e. must match the short name provided for the ultimateCreditor during mandate initiation). Mismatches will result in scheme rejections.
The unique contract reference number issued by the Ultimate Creditor to the Payer/Debtor when the contract was concluded. This value MUST perfectly match the Contract Reference stored on the active Mandate Register at the Debtor Bank. (i.e must match the identifier provided for mandate.mandateRequestIdentification during mandate initiation). Mismatches will result in scheme rejections.
Under the DebiCheck scheme, the user reference expected to appear on debtor statements comprises the following:
creditorAbbreviatedShortName - right-padded with spaces to exactly 10 characters (Characters 1–10)creditorContractReference - right-padded with spaces to exactly 14 characters (Characters 11–24)requestedCollectionDate (also known as cycle date) - formatted as YYMMDD (Characters 25–30)remittanceInformation in the DirectDebit. Only the first 30 characters are required to appear on debtor statements. Allowed characters are limited to printable characters.This field will be provided for all inbound requests to the partner. Do NOT populate this field for outbound requests. Instead, provide any bill presentment text (up to 110 characters) in the DirectDebit model under remittanceInformation.unstructured. The engine will automatically concatenate the Creditor Short Name, Contract Reference, the DirectDebit requestedCollectionDate, and your unstructured remittance text to construct the final 140-character string required by the scheme.
{ "creditorAbbreviatedShortName": "string", "creditorContractReference": "string", "userReference": "string" }
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.TCIB: Transactions Cleared on an Immediate Basis scheme.Scheme-specific data for Authenticated Collections (DebiCheck) direct debits. Unlike EFT, DebiCheck only supports debit transactions (collections), so shortened account numbers used for EFT file generation are not applicable here.
The Creditor Abbreviated Short Name (ABSN). This is a 3 to 10 character description of the Ultimate Creditor's name, business, or product that will appear on the debtor's bank statement. This value MUST perfectly match the ABSN stored on the active Mandate Register at the Debtor Bank (i.e. must match the short name provided for the ultimateCreditor during mandate initiation). Mismatches will result in scheme rejections.
The unique contract reference number issued by the Ultimate Creditor to the Payer/Debtor when the contract was concluded. This value MUST perfectly match the Contract Reference stored on the active Mandate Register at the Debtor Bank. (i.e must match the identifier provided for mandate.mandateRequestIdentification during mandate initiation). Mismatches will result in scheme rejections.
Under the DebiCheck scheme, the user reference expected to appear on debtor statements comprises the following:
creditorAbbreviatedShortName - right-padded with spaces to exactly 10 characters (Characters 1–10)creditorContractReference - right-padded with spaces to exactly 14 characters (Characters 11–24)requestedCollectionDate (also known as cycle date) - formatted as YYMMDD (Characters 25–30)remittanceInformation in the DirectDebit. Only the first 30 characters are required to appear on debtor statements. Allowed characters are limited to printable characters.This field will be provided for all inbound requests to the partner. Do NOT populate this field for outbound requests. Instead, provide any bill presentment text (up to 110 characters) in the DirectDebit model under remittanceInformation.unstructured. The engine will automatically concatenate the Creditor Short Name, Contract Reference, the DirectDebit requestedCollectionDate, and your unstructured remittance text to construct the final 140-character string required by the scheme.
{ "schema": "ZA_RTC", "schemeData": { "creditorAbbreviatedShortName": "string", "creditorContractReference": "string", "userReference": "string" } }