Skip to main content

Collection Files

In order to process collections, you will be required to upload collection files to Stitch's SFTP server by placing the file in the Outgoing folder. Stitch will validate the schema and data and send you a REPLY file containing validation results.

Once validation is completed, Stitch will process your valid collections. Once the processing is complete, Stitch will send you a final OUTPUT file detailing the results of the collections.

note

All valid collections will be processed. Should you have any validation errors, Stitch will send back a REPLY file with the failed collection items and the failure reasons. You will be required to correct the issues and submit only the collection requests that had errors as a new batch (the valid collections would have been previously processed).

Example:
If you submitted 10 collections and 3 failed validation, we will notify you via the REPLY file of the reasons the 3 collections failed validation. Stitch will process the 7 valid collections and you will only have to resubmit the 3 collections that failed validation as a new batch, once you have rectified the issues.

File Types and Validation

Collections involve 3 file types: Incoming, Reply and Output. They will all be in CSV format and all files will have 3 record types. These can be seen below:

Record typeDescription
HHeader record detailing overall information about the collection
DData record that contains the collection request details. All other records are metadata
TTrailer record that houses summary information

Incoming Collection File

This is the CSV file containing all your collection requests. You will be required to send this to Stitch to process your collections. The file structure is as follows:

FieldRecord typeDescriptionTypeExample value
ReferenceHCollection reference to uniquely identify the collection batchStringMY_REF
Submission dateHThe date the collection was submitted, in ISO8601 formatISO 86012023‐08‐31T12:11:20+07:00
IDDCollection mandate ID referencing the authorised mandate to collect againstStringbWFuZGF0ZS8zNjljY2RhMS1jZTQ0LTRiMmMtOThhMC05Mjk3ODNmYWY3NTU
ValueDThe amount to be collectedDecimal3000.00
Tracking periodDNumeric value indicating how many days from the collection date the account should be tracked for, up to a maximum of 10 i.e. 1,2,3,..10. Defaults to 0Integer1
Collection dateDThe collection date in line with what was agreed on in the mandate. Where date adjustment is allowed, this date could be differentISO 86012023-09-25
Total recordsTTotal number of collection items within the fileInteger25
Total tracking recordsTTotal number of collections with tracking period providedInteger5
Total valueTThe total value of all the collectionsDecimal10000.00
Total tracking valueTThe total value of all the tracking collectionsDecimal963.1

Sample Incoming Collection File

Download sample incoming file

Reply File

A REPLY file will inform you of validation results on your collection request and it will indicate whether the collection was submitted or not submitted. Once a file has been submitted, Stitch will perform 2 types of validation:

Should there be any schema or data validation errors, the collection will not be submitted and the errors will be detailed within the REPLY file. Only collection items with errors will be sent back in this REPLY file. You will have to resubmit ALL items, with corrections, as a new collection submission.

Here are the columns in a REPLY file. The columns are the same for both schema and data validation replies.

FieldDescriptionTypeExample value
Record typeWhat type of record it is. Values can be H, D, or TStringD
LineWhich line in the file this error pertains toInteger4
IDThe collection Id if the error is for a data item , where applicableStringbWFuZGF0ZS8zNjljY2RhMS1jZTQ0LTRiMmMtOThhMC05Mjk3ODNmYWY3NTU=
StatusThe status resulting from the validation. Value can only be ERRORStringbWFuZGF0ZS8zNjljY2RhMS1jZTQ0LTRiMmMtOThhMC05Mjk3ODNmYWY3NTU=
Error codeTells you why the collection was not submitted. The code can be either SCHEMA_VALIDATION_FAILED or DATA_VALIDATION_FAILED.
If the data validation failed, the file will be populated with the rows failing data validation with reasons.
StringSCHEMA_VALIDATION_FAILED
Error reasonIt provides more information about the error code. Why the record failed schema or data validationStringHEADER_RECORD_REQUIRED

Schema Validation

Schema validation will involve validating that the file that was sent to Stitch abides by the expected schema.

Failure would result in a SCHEMA_VALIDATION_FAILED error reason in the REPLY file header. When a file fails schema validation, no collections will be processed.

The table below provides more details about the "Error reason" informing you about which part of the schema failed validation:

FieldRuleError reasonDescription
Header recordsHeader record requiredHEADER_RECORD_REQUIREDHeader record required
Header recordsValidate the titles of the header rowsINVALID_HEADER_RECORD_TITLEIncorrect header titles provided
Header recordsNumber of header record fieldsINVALID_HEADER_RECORDIncorrect number of header record fields provided
Data recordsValidate the titles of the detail rowsINVALID_DETAIL_RECORD_TITLEIncorrect detail titles provided
Data recordsNumber of detail record fieldsINVALID_DETAIL_RECORDIncorrect number of detail record fields provided
Data recordsAt least one detail record requiredDETAIL_RECORD_REQUIREDDetails record required
Trailer recordsValidate the titles of the trailer rowsINVALID_TRAILER_RECORD_TITLEIncorrect trailer titles provided
Trailer recordsTrailer record requiredTRAILER_RECORD_REQUIREDTrailer record required
Trailer recordsNumber of trailer record fieldsINVALID_TRAILER_RECORDIncorrect number of trailer record fields provided
GeneralIncorrect record type specified in the record type fieldINCORRECT_RECORD_TYPEIncorrect record type specified. This may be due to an unexpected ordering of the provided record types.
Example Reply File

Sample REPLY file - Schema validation failure

Data Validation

Data validation is carried out on all Data record types within the file. A validation failure would result in a DATA_VALIDATION_FAILED error reason in the REPLY file header with each data validation error reason appearing alongside each collection row. Formatting rules are used to validate if the format or schema of the file adheres to the format rules. Data rules will validate whether the data of each item in the file adheres to the data rules.

note

If the header of a collection file fails data validation, the entire file will not be processed! If the header of a collection file passes data validation, but the data records fail data validation, the header will be processed and the data records that pass data validation will be processed. The data records that fail data validation will be sent back in the REPLY file.

Formatting Rules
FieldRuleError reasonDescription
ReferenceBatch reference requiredBATCH_REFERENCE_REQUIREDMissing batch reference
Submission dateISO 8601 format for submission dateINVALID_SUBMISSION_DATEInvalid submission date provided
IDFormat should be a base64 stringINVALID_IDInvalid ID provided
Collection dateISO 8601 format for dateINVALID_DATEInvalid date provided
ValueDecimal format for valueINVALID_VALUEInvalid value provided
Tracking periodInteger format for tracking periodINVALID_TRACKING_PERIODInvalid tracking period provided
Data rules
FieldRuleError reasonDescription
ReferenceBatch references should be unique for batches that pass schema validationDUPLICATE_BATCH_REFERENCEA batch with this reference already exists
IDID should match an authorised, active mandateUNMATCHED_MANDATEInvalid mandate ID provided
Submission dateDate must be current dateINVALID_DATEInvalid date provided
Collection dateDate should match what's on the mandateINVALID_DATEInvalid date provided
Collection dateDate should be a date in the future (at least 1 day in the future)INVALID_DATEInvalid date provided
ValueValue should match what's on the mandateINVALID_VALUEInvalid value provided
Tracking periodIf this value is > 0, the mandate should have tracking enabledUNABLE_TO_TRACKUnable to track on this mandate
Tracking periodValue should be >0 and ≤10INVALID_TRACKING_PERIODInvalid tracking period provided. Tracking period should be between 0 and 10 days
Total recordsShould be equal to the total count of the D recordsMISMATCHED_TOTAL_RECORDSTotal records does not match total details records provided
Total valueShould be equal to the sum of the value of the D recordsMISMATCHED_TOTAL_VALUETotal value does not match the sum of the value of the details records provided
Total tracking recordsShould be equal to the total count of the D records with a tracking period >0MISMATCHED_TOTAL_TRACKING_RECORDSTotal tracking records does not match the records with tracking period>0 provided
Total tracking valueShould be equal to the sum of the value of the D records with a tracking period >0MISMATCHED_TOTAL_TRACKING_VALUETotal tracking value does not match the sum of the value of the details records with tracking period >0 provided
Sample Reply File

Sample REPLY file - Data validation failure for the header
Sample REPLY file - Data validation failure for the data and trailer

Output File

An OUTPUT file will be used to inform you of the collection results for all the valid collections that were submitted. It is the final file that will be received for collections, for the day.

FieldRecord typeDescriptionTypeExample value
CURRENT_DATEHThe date on which the OUTPUT file was generated and uploaded to your SFTP Incoming folder, in ISO8601 formatISO 86012023-08-19T12:11:20+07:00
STATEMENT_REFERENCEHstatement reference for the batch. This will correspond with the line item on your bank statement for the settlement.StringRANDOM_REF
REFERENCEDThe original batch reference that this collection item belongs toStringMY_COLL_03
IDDMandate IDStringbWFuZGF0ZS8zNjljY2RhMS1jZTQ0LTRiMmMtOThhMC05Mjk3ODNmYWY3NTU
Collection dateDDate on which the funds are to be collected, in ISO8601 formatISO 86012023-09-25
ValueDCollection valueDecimal653.04
Tracking periodDNumeric value indicating how many days after the collection date the account should be tracked for. Values expressed as number of days for up to a maximum of 10 i.e. 1,2,3,..10Integer3
StatusDCollection statusStringFAILED
ReasonDCollection status reason for failed collectionsStringIncorrect date
TypeDIndicates the type of debicheck. The value can either be RMS or DCStringDC
Total recordsTTotal # of collection items within the fileInteger25
Total valueTTotal value of the items to collect onDecimal10000.00
Total success recordsTTotal number of successful collectionsInteger15
Total success valueTValue of successful collectionsDecimal7856.00
Total failed recordsTTotal number of failed collectionsInteger10
Total failed valueTValue of failed collectionsDecimal2254.00
Total tracking recordsTTotal number of tracking collectionsDecimal4
Total tracking valueTValue of failed collectionsDecimal54.00
Total tracking successTTotal number of successful tracking collectionsDecimal3
Total tracking success valueTValue of successful tracking collectionsDecimal14.00
Total tracking failedTTotal number of failed tracking collectionsDecimal1
Total tracking failed valueTValue of failed tracking collectionsDecimal40.00
Sample Output file

Download sample OUTPUT file

Collection Request Statuses

Below are the possible statuses that can be received in an OUTPUT file on a batch level

StatusRecord typeStatus codeDescription
SUBMITTEDHSUBMITTEDCollection batch has been submitted
NOT_SUBMITTEDHNOT_SUBMITTEDCollection batch has not been submitted due to schema or data validation error

Below are the possible statuses that can be received in an OUTPUT file per collection line item.

StatusRecord typeStatus codeDescription
SUCCESSDPROCESSEDCollection was successful
FAILEDDPAYMENT_SUSPENDEDPayment stopped by account holder
FAILEDDINSUFFICIENT_FUNDSInsufficient funds in the debtors account
FAILEDDREAUTHENTICATION_REQUIREDMandate needs to be re-authenticated
FAILEDDBANK_ERRORA system error occurred at the bank
FAILEDDBANK_PROCESSING_ERRORCreditor bank unable to process due to problem
FAILEDDINACTIVE_ACCOUNTAccount frozen, account in liquidation, account closed, or account holder deceased
FAILEDDINVALID_ACCOUNTDebits not allowed on this account, account not found, or debtor account number fails CDV routine
FAILEDDBENEFICIARY_BANK_PROCESSING_ERRORCreditor bank unable to process due to problem
FAILEDDMANDATE_SUSPENDEDMandate is suspended
FAILEDDINVALID_USER_REGISTRATIONUser not correctly registered
FAILEDDDUPLICATE_TRANSACTIONDuplicate transaction identified, there is another transaction already in progress with this mandate ID
PENDINGDPENDINGCollection did not go through, but there is still time for it to be actioned and so it should not yet be resubmitted