File Specification: VAS

Electrum Digital Goods and Services Reconciliation Extract File Specification, version 8.3

File Name

An Electrum reconciliation file name should have the following format:

Representative file name examples:

ELECTRUM_STELLR_EXTRACT_SUV_MATCHED_20230131_1675188000.csv
SWITCHONE_ELECTRUM_EXTRACT_AIRTIME_MARKOFF_20231116_1700197212.csv
CONTOUR_ELECTRUM_EXTRACT_PPU_MARKOFF_20231116_1700179200.csv

Element name	Description
CREATOR IDENTIFIER	The CREATOR IDENTIFIER element will be populated with a fixed-value string that is used by the reconciliation system to identify the entity that produced the file.
PARTNER IDENTIFIER	The PARTNER IDENTIFIER element will be populated with a fixed-value string that is used by the reconciliation system to identify the partner entity involved in the reconciliation process alongside the file CREATOR.
EXTRACT	The EXTRACT element is used to specify the contents of the extract when multiple separate extracts are required per service.
SERVICE	The SERVICE element is set if specified in the SPD. It defines if the extract is for a specific service and not general to all services. It may be one of the following values: AIRTIME BILLPAY PPU SUV LOTTO MONEYTRANSFER
EXTRACT NAME	The EXTRACT NAME element describes where the extract originates from and will be one of the following values: MARKUP - from the originating channel MARKOFF - from the servixce provider SWITCH - from Electrum
PERIOD END DATE	The PERIOD END DATE element will be populated with the date of the end of the current reporting window as defined by the RFC 3339 profile of the ISO 8601 standard. The format used in the filename should be YYYYMMDD, according to ISO 8601. For example, 20220915.
EXECUTION EPOCH TIME	The EXECUTION EPOCH TIME element will be populated with the epoch time of when the file is generated.

Epoch time is defined as the scalar number of seconds after 00:00:00 UTC on 1 January 1970. This element is used to ensure that the filename is unique if multiple files are generated on the same day.

File Structure

The Electrum reconciliation file is a plain (ASCII) text file consisting of two sections, the end of each being marked by an End of Line (EOL, HEX ‘0D0A’) character:

Header
Body

While the header contains exactly one line record, the body consists of multiple line records, each of which represents an individual transaction record. Each line record in the header and body consists of a set of comma-delimited, fixed-length fields.

Field Types

Each field in a reconciliation file can be one of the following types:

Field Type	Description
O – Optional	This field is optional
M - Mandatory	The field is mandatory, and will be used by Electrum to link transaction records between different files, compare these transaction records to determine their reconciliation status, or to perform settlement actions on the reconciled transaction record.

Note

Optional fields are marked as such to indicate that these fields are not required by any processes within the reconciliation and settlement systems. However, it is recommended that all available fields of a transaction are included in the recon file. Also note that, in the case where an optional field is not populated, the comma for delimiting this field must still be present; that is, the field should still be present in the line record but be left without data.

Field Elements

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

Field Element	Description
[0-9]	Numeric characters
[A-Z]	Alphabetic characters, capitalised
[a-z]	Alphabetic characters, uncapitalised
[A_Z]	Alphabetic characters, capitalised or underscored ("_")
[-~]	All printable characters, including numeric, alphabetic, and special characters, excepting comma (,) or new line characters (e.g., \n)
List{}	The field value must be one of the values in the supplied list.
RFC 3339	The format for date, time and timezone 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, the default zone information is UTC (Z).

Field Elements - Minimum Length Padding

If no length is dictated in the Format column for a field then no padding is required. A field marked as 'O – Optional' may be omitted by keeping the value unpopulated. However if a value is supplied, the format length requirements must be applied. If the value supplied does not meet the minimum length requirement, the following padding should be applied to the value:

Field Element	Padding to Apply	Example
[0-9] length 10	Left pad with zeros	25 becomes 0000000025
[A-Z] length 10	Left pad with spaces	ABC will become ____ABC
[a-z] length 10	Left pad with spaces	abc will become ____abc
[-~] length 10	Left pad with spaces	ab12* will become ____ab12*

File Header

Element	Value	Format	Notes
File format type	VAS	[A-Z]	This will be a constant, fixed string.
File format version	E.g., 8.3	[␣-~]; length 20	The version of the file format being used. Equivalent to the version of the latest file specification.
Batch start date time	E.g., 2019-06-25T23:59:59.999+02:00	[RFC 3339]	The date and time after which transactions will fall in the current reporting window.
Batch end date time	E.g., 2019-06-25T23:59:59.999+02:00	[RFC 3339]	The date and time after which transactions will fall in the next reporting window.
Execution date time	E.g., 2019-06-25T23:59:59.999+02:00	[RFC 3339]	The date and time of file generation.

File Body

	Element	Value	Format	Mandatory/Optional	Notes
1	Advice ID	E.g.: 7887077f-ccc9-4ed5-a236-ece87917c76e	[UUID]; length 36	O	The value of the `id` field in the advice request/response message pair between Electrum and the originating system.
2	Request ID	E.g.: 7887077f-ccc9-4ed5-a236-ece87917c76e	[UUID]; length 36	M	The value of the `id` field in the authorisation request/response message pair between Electrum and the originating system.
3	Service type	AIRTIME, BILL PAYMENT, LOTTO, MONEY TRANSFER, PREPAID UTILITY, or SUV	[A-Z]; length 20	M	A fixed value from an enumerated list, based on the service relevant to the transaction
4	Error type	[ERROR TYPE]	[␣-~]; length 0-50	O	Only included in the case that a transaction is declined/fails. This will be the value populated in the `errorType` field as persisted in the Electrum system, after an error occurs at Electrum, or Electrum receives an error response from the service provider.
5	Provider error code	[Service provider error response code ]	[␣-~]; length 0-500	O	Only included in the case that a transaction is declined/fails. This will be populated with the error response code received at Electrum from the service provider.
6	Request date time	E.g., 2019-06-25T23:59:59.999+02:00	[RFC 3339]	M	The value of the time stamp in the request/response message pair between the originating system and Electrum
7	Merchant ID	[Merchant ID]	[␣-~]; length 15	M	This will identify the merchant that initiated the transaction, and will be the value of the `originator.merchant.merchantId` field in the authorisation request/response message pair between the originating system and Electrum.
8	Originator ID	[Originator institution ID]	[␣-~]; length 4-20	M	This will identify the originator that generated the transaction, and will be the value of the `originator.institution.id` field in the authorisation request/response message pair between the originating system and Electrum.
9	Receiver ID	[Receiver institution ID]	[␣-~]; length 4-20	O	This will identify the product supplier that must ultimately be involved in the settlement of the transaction, and will be the value of the `receiver.id` field in the authorisation request/response message pair between the originating system and Electrum.
10	Receiver name	[Receiver institution name]	[␣-~]; length 0-50	O	This will identify the product supplier that must ultimately be involved in the settlement of the transaction, and will be the value of the `receiver.name` field in the authorisation request/response message pair between the originating system and Electrum.
11	Settlement entity ID	[Settlement entity institution ID]	[␣-~]; length 4-20	O	This will identify the service provider or aggregator that authorised the transaction and will be the value of the `settlementEntity.id` field in the authorisation request/response message pair between the originating system and Electrum.
12	RRN	[rrn]	[␣-~]; length 12	O	This will be the value of the `rrn` field in the authorisation request/response message pair between the originating system and Electrum.
13	STAN	[stan]	[␣-~]; length 6	O	This will be the value of the `stan` (System Trace Audit Number) field in the authorisation request/response message pair between the originating system and Electrum.
14	Originator Reference	[Originator reference number]	[␣-~]; length 1-50	O	This will include the merchant's reference number and will be the value of the `thirdPartyIdentifier.transactionIdentifier` field corresponding to the originating entity in the authorisation request/response message pair between the originating system and Electrum.
15	Settlement Entity Reference	[Settlement Entity reference number]	[␣-~]; length 1-50	O	This will include the transaction identifier/reference number assigned or required by the service provider, and will be populated with the value of the `thirdPartyIdentifier.transactionIdentifier` field corresponding to the `settlementEntity.id` in the authorisation request/response message pair between the originating entity and Electrum.
16	Service Reference	[BillPay reference number, prepaid utility meter number, MSISDN, or voucher serial number]	[␣-~]; length 1-50	O	For BillPay, this will be the BillPay reference number or traffic fine notice number as per the value of the `accountRef` or `noticeNumber` field in the authorisation request/response message pair between the originating system and Electrum. For a PPU transaction, this will be the utility meter number, as per the value of the `meterId` field in the authorisation request/response message pair between the originating system and Electrum. For an Airtime purchase, this will be the MSISDN (if present), as per the value of the `msisdn` field in the authorisation request/response message pair between the originating system and Electrum. For an SUV transaction, this will be the voucher code, as per the value of the `voucher.serialNumber` field in the authorisation request/response message pair between the originating system and Electrum. For a Lotto transaction, this will be the draw ID, as per the value of the `wager.drawID` field in the authorisation request/response message pair between the originating system and Electrum. For a Money Transfer redeem transaction, this will be the order redeem reference, as per the value of the `orderRedeemRef` field in the authorisation request/response message pair between the originating system and Electrum.
17	Product ID	[Product ID]	[␣-~]; length 0-50	O	The ID associated with the product that was provisioned or purchased. It is the value found in the `product.productId` field in the authorisation request/response message pair between the originating system and Electrum.
18	Transaction amount	[XXXXXX]	[0-9]; length 1-19	M	For a PPU transaction, this will be the value of the `purchaseAmount.amount` field (minor denomination) in the authorisation request/response message pair between the originating system and Electrum. For an airtime, bill payment, SUV, lotto or money transfer purchase transaction, this will be the value of the `requestAmount`.amount field (minor denomination) in the authorisation request/response message pair between the originating system and Electrum.
19	State	[AUTHORISED, CONFIRMED, REVERSED]	[A-Z]; length 1-20	M	This field will be populated as follows: AUTHORISED if an approval response message was received from the service provider at Electrum. CONFIRMED if the final advice message sent between all entities was a `TenderAdvice`. REVERSED if the final advice message sent between all entities was a `BasicReversal`.	The field will be left empty if no response was received from the service provider at Electrum.
20	Tender type	[Tender type]	[A-Z]; length 1-20	O	[CASH, CHEQUE, CREDIT_CARD, DEBIT_CARD, WALLET, ROUNDING, GIFT_CARD, LOYALTY_CARD, OTHER] The `tenderType` of the first tender associated with the transaction is used to populate the field. If no tenders are present this field is not populated.
21	Terminal ID	[Originator terminal ID]	[-~]; length 8	M	This will identify the originator terminal ID that generated the transaction, and will be the value of the `originator.terminalId` field in the authorisation request/response message pair between the originating system and Electrum.
22	Operator ID	[Originator operator ID]	[-~]; length 0-50	O	This will identify the originator operator ID that initiated the transaction, and will be the value of the `originator.operatorId` field in the authorisation request/response message pair between the originating system and Electrum.
23	Tender Card Number	[Tender card number]	[0-9]; length 12-19	O	The `tender.cardNumber` of the first tender associated with the transaction is used to populate the field. This will be a PCI compliant masked card number, with at least the first 6 digits in the clear. If no tenders are present the field is not populated.
24	Quantity	E.g., 1	[0-9]; length 1-10	O	This will be the number of products in the authorisation request/response message pair between the originating entity and Electrum. This value usually defaults to 1, except for the PPU product in which multiple meter tokens may be returned in one message.

Example file

Below is an example VAS .csv file with dummy data. Note that certain optional fields are populated while others are empty, however this does not imply that these fields would always be populated in this manner across all VAS services - they are optionally populated based on an individual integration’s requirements.

text