File Specification

The file name of a payments extract file should have the following format:

[ENTITY]_[FILE TYPE]_[SCHEME]_[REPORT NAME]_[PERIOD END DATE]_[FILE CREATION TIME].csv

In the above format:

ENTITY is a fixed-value string that is used by Electrum’s Back Office system to identify or recognise the entity that is supplying the file to Electrum, or to whom Electrum is supplying the file. This value could either be an entity name or identifier, and the specific value to use will be provided by Electrum during the implementation of the service.
FILE TYPE should be one of the following values:
- EXTRACT - for a transactions extract supplied to or by Electrum
- MATCHED - for a matched recon report supplied by Electrum
- UNMATCHED - for an unmatched recon report supplied by Electrum
SCHEME is an element that specifies the particular CHP (Clearing House Payments) service of the transactions in the file, and should be one of the following values:
- RPP
- RTC
- EFT
- AC
REPORT NAME is a string that describes the contents of the extract. This is useful to distinguish between extracts when multiple separate extracts are required for a service. Note that this field is generally not used by Electrum for processing purposes but may be used by an external entity to provide a user-friendly description of the file. The string in this field should be alphanumeric without spaces or special characters.
PERIOD END DATE specifies the date on which the reporting window of transactions in the file has ended, in the format YYYYMMDDhhmmss. FILE CREATION TIME is populated with the epoch timestamp of the file being generated, in the format YYYYMMDDhhmmss. This element is used to ensure that the filename is unique, in the case of multiple files being generated for the same reporting window.

File Generation

Electrum’s Back Office engine supports multiple files for a given reporting window where relevant. The following practices should be followed when generating a file that will be consumed by Electrum:

It is important to note that all transactions in a single file should conform to the same CHP payments scheme, namely, RPP, RTC, EFT, or AC. The particular scheme is indicated in the Scheme element of the header record in the file.
However, you may include both inbound and outbound transactions pertaining to the same scheme in the same file, or you may choose to use separate files for inbound and outbound transactions. Likewise, in the case of EFT, you may include all EFT-Debit and EFT-Credit transactions in a single file, or you may choose to use separate files. The specific service (inbound or outbound, debit or credit, etc.) is indicated in the Service Type element for each transaction record in a file.
If a fault is encountered during file generation and a file could not be generated completely, then a new file should be generated with all transaction records that were meant to be in the original file. For example, if the first generation attempt was only able to insert 400 transaction records out of a total of 1000 records that exist in a given reporting window, then a new file should be generated with all 1000 records.
To inform Electrum whether a given file was the final generated file for a given reporting window, or whether more files should be expected, an indicator must be set in the file footer.

Field Types

Each field in a transactions extract file can be described as one of the following types:

Field Type	Notes
O - Optional	This field is optional. In extract files generated and supplied by Electrum, the field will be included if it is available from the messages processed via the Electrum switch. In extract files generated by an Electrum customer or third party and supplied to Electrum for recon purposes, this field may be omitted as recon processing is not dependent on this field. However, if a party wishes Electrum recon reports (matched and unmatched reports produced as a result of recon processing by Electrum Back Office), then this field should be included in the extract file.
M - Mandatory	This field is mandatory. In extract files generated by Electrum, this field will always be included. In extract files supplied to Electrum, this field must be populated regardless of the CHP service, as Electrum needs the field value for recon purposes.
C - Conditional	This field is mandatory if certain conditions are met. These conditions will be clearly described for the relevant field. In all other cases, the field can be treated as optional.

Field Formatting

In each of the header and body sections, the following data elements may be used:

Data Elements	Notes
[0-9]	Numeric characters
[A-Z]	Alphabetic characters capitalised
[a-z]	Alphabetic characters uncapitalised
[A-Z_]	Alphabetic characters, capitalised, or underscore (_)
[-~]	All printable characters, including numeric, alphabetic, and special characters, except new line characters (e.g., \n). Notes: In the case where the field value itself contains a comma (,) the entire field value should be in double-quotes, for example: “Ben, lunch”. If, further, the field value itself also contains double-quotes, then a double-quote appearing inside the field must be preceded with another double-quote.
List{}	The field value must be one of the values in the supplied list.
RFC 3339	The format for date, time, and time zone values, as defined by the RFC 3339 profile of the ISO 8601 standard. All date/time stamps are required to have the appropriate time zone, where the default zone information is UTC (Z).

Note: In general, the CSV formatting specifications defined by RFC4180 should be followed (see Section 2 in https://datatracker.ietf.org/doc/html/rfc4180).

File Structure

The transactions extract file is a plain (ASCII) text file consisting of three sections. All records in the file are separated by a new line using the carriage return (0x0D ‘\r) and line feed (0x0A ‘\n) characters. It is not necessary to end the footer with a new line, though this is permissible.

Header
Body
Footer

While the header and footer contain exactly one record each, the body consists of multiple records, each of which represents an individual transaction record. Each line record in the header, body, and footer consists of a set of comma-delimited fields. The tables below describe the header, body, and footer field elements. Please refer to the appendix for a description of field types and formatting that are used in these tables.

File Header Fields

Element	Example Value	Format	Type	Notes
File format type	CHP	List{VAS, CHP}	M	A constant, fixed string.
File Format Version	1.2.0	[-~]	M	The version of the file format being used, and equivalent to the version of this specification.
Scheme	RPP	List{RPP, RTC, EFT, AC}	M	A string that describes the regulated payment stream pertaining to the transaction.
Batch Start Date Time	2019-06-25T23:59:59.999+02:00	[date-time as defined by RFC 3339]	M	The date and time from which transactions started to fall in the current reporting window.
Batch End Date Time	2019-06-25T23:59:59.999+02:00	[date-time as defined by RFC 3339]	M	The date and time after which transactions will fall in the next reporting window.
Creation Date Time	2019-06-25T23:59:59.999+02:00	[date-time as defined by RFC 3339]	M	The date and time of file generation.

File Body Fields

Element	Example Value	Format	Type	Notes
Direction	IN	List{IN, OUT, ON-US}	M	A string that describes the direction of the payment from the perspective of the participant. That is, a payment with direction ‘IN’ is one that was initiated by an external industry bank and received for processing by the local system. A payment with direction ‘OUT’ is one that was initiated by the local system and sent outbound via the industry to a relevant bank.
Transaction Type	CREDIT	List{CREDIT, DEBIT, UNPAID, RECALL, SEC}	M	For RTC and RPP transactions, this field should always be CREDIT. For EFT and AC (Debicheck) transactions, this field should be populated with a value corresponding to the appropriate transaction type.
End-to-End Transaction ID	7887077f-ccc9-4ed5-a236- ece87917c76e	[-~]	O	The value of the end-to-end transaction ID of the transaction that was processed and that is now used to populate this transaction record. In a CHP payment transaction, this is a unique identification, as assigned by the initiating party, to unambiguously identify a given transaction. This identification is passed on, unchanged, throughout all messages in the entire end-to-end chain.
UETR	7887077f ccc9-4ed5-a236- ece87917c76e	[-~]	M	The value of the UETR of the transaction that was processed and that is now used to populate this transaction record. In a CHP payment transaction, this is a unique identification, this is a unique identifier that remains the same for all messages related to the same transaction.
Creditor Agent BIC	BKSVZAJJ	[A-Z, 0-9]	C	The value of the Creditor Agent Bank Identification Code of the transaction that was processed and that is now used to populate this transaction record. Note: For certain schemes such as EFT, the Bank Identification Code may not be available from the transaction messages, in which case this field can be populated with the relevant bank’s branch code instead. Conditional field: In most cases, this field should be populated. In rare instances where the creditor bank or agent does not have a BIC or bank branch code, this field may be left empty and the Creditor Agent Member ID field should be populated instead.
Creditor Agent Member ID		[0-9]	C	The Member ID of the creditor/beneficiary bank. Conditional field: This field is only needed if the Creditor Agent BIC field is left empty.
Creditor Agent Branch Code		[0-9]	C	The branch code of the creditor/beneficiary bank. Conditional field: This field is needed if the Scheme in the file header is set as ‘EFT’, and if neither the Creditor Agent BIC nor the Creditor Agent Member ID fields could be populated.
Creditor Domain		[A-Z, 0-9]	O	The domain pertaining to the beneficiary (a.k.a., payee) of the payment. This field is optional and is only applicable if the Scheme field in the file header is RPP and if the transaction for the given record is a proxy-based-payment. The domain value of a proxy-based RPP payment may be useful to indicate the domain of a business partner in the case of a payment pertaining to Electrum’s Business Partner Payments services.
Creditor Account Number	42313726810	[-~]	O	The account number of the beneficiary (a.k.a., payee) of the transaction. The creditor is a person or business into whose bank account a payment has been made.
Debtor Agent BIC	BKSVZAJJ	[A-Z, 0-9]	C	The value of the Debtor Agent Bank Identification Code of the transaction that was processed and that is now used to populate this transaction record. Note: For certain schemes such as EFT, the Bank Identification Code may not be available from the transaction messages, in which case this field can be populated with the relevant bank’s branch code instead. Conditional field: In most cases, this field should be populated. In rare instances where the debtor bank or agent does not have a BIC or bank branch code, this field may be left empty and the Debtor Agent Member ID field should be populated instead.
Debtor Agent Member ID		[0-9]	C	The Member ID of the debtor/recipient bank. Conditional field: This field is only needed if the Debtor Agent BIC field is left empty.
Debtor Agent Branch Code		[0-9]	C	The branch code of the debtor/recipient bank. Conditional field: This field is needed if the Scheme in the file header is set as ‘EFT’, and if neither the Debtor Agent BIC nor the Debtor Agent Member ID fields could be populated.
Debtor Domain		[A-Z, 0-9]	O	The domain pertaining to the sender (a.k.a., payer) of the payment. This field is optional and is only applicable if the Scheme field in the file header is ZA-RPP and if the transaction for the given record is a proxy-based-payment. The domain value of a proxy-based RPP payment may be useful to indicate the domain of a business partner in the case of a payment pertaining to Electrum’s Business Partner Payments services.
Debtor Account Number	42313726810	[-~]	O	The account number of the payer of the transaction. The debtor/payer is the individual who has made a payment from their bank account to the bank account of another person or business.
Currency	ZAR	List{ZAR}	M	The currency code of the amount of the transaction.
Amount	500.00	In denomination of the indicated currency, in the format [major units].[minor units] with the number of minor units (fractional digits) compliant with the number of decimal places published in ISO 4217.	M	The settlement amount of the transaction. In a CHP payment transaction, this is the amount of money to be moved between the instructing and instructed agent, which may include charges or deductions, expressed in the currency of the initiating party.
Settlement Date & Time	2019-06-25T23:59:59.999+02:00	[date-time as per RFC 3339]	M	The date and time on which the amount of money should cease to be available to the agent that owes it (the Debtor Agent) and when the amount of money becomes available to the agent to which it is due (the Creditor Agent).
Settlement Pool Reference	0001	[-~]	C	This is a number that describes which BankservAfrica settlement pool the transaction fell into. Conditional field: This field will be populated in matched and unmatched files produced by Electrum where reconciliation was performed with a BankservAfrica file. External entities supplying files to Electrum can treat this field as optional. Note: This field may be used to indicate bulk posting references.
User Reference		[-~]	O	This is an optional reference added by the customer who initiated the transaction.
Business Reference		[-~]	O	This is a unique alphanumeric value that is sometimes generated by the originating bank.
RRN		[-~]	C	For RTC transactions, this field is populated with the End-to-End Transaction ID. Conditional field: This field will be populated in matched and unmatched files produced by Electrum for the RTC stream, where reconciliation was performed with a BankservAfrica file.
Transaction Date & Time	2019-06-25T23:59:59.999+02:00	[date-time as defined by RFC 3339]	M	The date and time at which the transaction message was created for the transaction that was processed and that is now used to populate this transaction record.
State	APPROVED	List{APPROVED, CANCELLED, PENDING, REJECTED}	M	The final state of the transaction. Note that the REJECTED state reflects all cases where the transaction was declined or has otherwise failed during processing.

File Footer Fields

Element	Example Value	Format	Type	Notes
Is Final	Yes	List{YES, NO}	M	An indicator of whether this file is the last file of its type produced by the particular entity for the given reporting window, or if more files will be produced for remaining transactions.
File Number	3	[0-9]	M	An indicator of the number of files of its type that have been produced by the particular entity for the given reporting window, including the current file. Notes: This number should be unique for every file in the reporting window for the same process/filename. There should not be any gaps between files (i.e., file numbering should follow without gaps). Whichever file has the Is Final field set to Yes should also have the maximum File Number value. It is recommended that the order of transactions across files should match the order of the File Number; that is, for the first transactions to be included in file number 1 onwards and the latest transactions to be in the latest file submitted.
Transaction Count	20000	[0-9]	M	The total number of line records representing individual transactions that are included in the current file, excluding header and footer records.