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.


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).

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

In the case of no validation errors on submitted collections, you will receive a REPLY file as an acknowledgement, indicating a successful submission.

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 are required to send this to Stitch to process your collections. The file structure is as follows:

FieldRecord typeDescriptionTypeExample value
EXTERNAL_BATCH_REFERENCEHClient specified reference to uniquely identify a collection batch.StringMY_REF
SUBMISSION_DATETIMEHThe datetime the collection was submittedISO 86012023‐08‐31T12:11:20+07:00
EXTERNAL_COLLECTION_REFERENCEDClient specified reference to uniquely identify a collection.ISO 86012023‐08‐31T12:11:20+07:00
CONSENT_IDDThe Payment Consent ID for the authorised mandate to collect againstStringbWFuZGF0ZS8zNjljY2RhMS1jZTQ0LTRiMmMtOThhMC05Mjk3ODNmYWY3NTU
VALUEDThe amount to be collectedDecimal3000.00
COLLECTION_DATEDThe collection date in line with what was agreed on in the mandate. Where dateAdjustmentAllowed has been enabled, this date could be differentISO 86012023-09-25
TOTAL_RECORDSTTotal number of collection items within the fileInteger25
TOTAL_VALUETThe total value of all the collectionsDecimal10000.00

Sample Incoming Collection File

Download sample incoming file

  • CONSENT_ID is the Payment Consent ID returned by the Stitch API during Payment Consent creation.
  • dateAdjustmentAllowed is as per your client configuration as setup during onboarding. This indicates that the collection date can differ from what's on the mandate.

Reply File

A REPLY file will inform you of validation results on your collection request and and will indicate which items within the collection batch were submitted, and which were not. Once you have submitted a collection batch file, Stitch will perform two types of validation:

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

FieldDescriptionTypeExample value
RECORD_TYPEThe type of record it is. Values can be H, D, or TStringD
LINEWhich line in the file this error pertains toInteger4
CONSENT_IDIn the case of a data validation error, the consent ID for the collection line itemStringbWFuZGF0ZS8zNjljY2RhMS1jZTQ0LTRiMmMtOThhMC05Mjk3ODNmYWY3NTU=
VALIDATION_RESULTThe status result from the validation. Value can only be ERRORStringERROR
ERROR_CODEIndicates why the collection was not submitted. The code can be either SCHEMA_VALIDATION_FAILED or DATA_VALIDATION_FAILED.
If data validation failed, the file will be populated with the rows failing data validation with accompanying reasons.
ERROR_REASONProvides detailed information about the error code and reason for the failed schema or data validation.StringHEADER_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 and, where possible, the data records that failed schema validation. When a file fails schema validation, no collections in that file will be processed.

The table below details possible values for "Error reason", indicating 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 Invalid Reply File

Download sample REPLY file - Schema validation failure

Data Validation

Data validation is carried out on all "Data" (D) record types within the file.

  • Formatting rules are used to validate if the format or schema of the file adheres to the format rules.
  • Data rules are used to validate whether the data of each item in the file adheres to the data rules.

A validation failure would result in a DATA_VALIDATION_FAILED error code in the REPLY file header with each data validation error reason appearing alongside each collection row.

Validation failure
  • If the header record of a collection file fails data validation, the entire collection file will not be processed!
  • If the header record 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 for correction and resubmission in the REPLY file.
Formatting Rules
FieldRecord typeRuleError reasonDescription
EXTERNAL_BATCH_REFERENCEHBatch reference requiredBATCH_REFERENCE_REQUIREDMissing batch reference
SUBMISSION_DATETIMEHISO 8601 format for submission datetimeINVALID_SUBMISSION_DATEInvalid submission date provided
CONSENT_IDDThe payment consent ID stringINVALID_IDInvalid ID provided
COLLECTION_DATEDISO 8601 format for dateINVALID_DATEInvalid date provided
VALUEDDecimal format for valueINVALID_VALUEInvalid value provided
Data rules
FieldRuleError reasonDescription
EXTERNAL_BATCH_REFERENCEBatch references should be unique for batches that pass schema validationDUPLICATE_BATCH_REFERENCEA batch with this reference already exists
CONSENT_IDID should match an authorised, active mandateUNMATCHED_MANDATEInvalid consent ID provided
SUBMISSION_DATETIMEDate 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
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
Sample Reply File

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

Collection Request Statuses

Below are the possible statuses that can be received in a REPLY file when schema and data validation are successful. These are represented in the "Header" (H) record:

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

Output File

An OUTPUT file will be used to inform you of the collection results for all the valid collections that were submitted, as well as their associated settlement status. It is the final file that will be received for collections. You will receive this file daily, and it will reflect any updates to collections that were processed during the day.

FieldRecord typeDescriptionTypeExample value
RECORD_TYPEH,D,TDenotes the record type. Either H, T, or DStringH
CREATED_DATETIMEHThe 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
EXTERNAL_BATCH_REFERENCEDThe client specified batch reference, as it was supplied in the original collection file.StringMY_COLL_03
EXTERNAL_COLLECTION_REFERENCEDThe original external collection reference for the collection, as supplied by you in the Incoming fileStringMY_COLL_03
COLLECTION_IDDThe unique ID for the collectionStringZGUxZGM5NDItMGNkYS00ZDgzLTkxYzctMzY0N2MxODJlNGE5
COLLECTION_DATEDDate on which the funds were collected, in ISO 8601 formatISO 86012023-09-25
VALUEDCollection valueDecimal653.04
COLLECTION_STATUSDThe status of the collection from the debtorStringFAILED
COLLECTION_REASONDReason for the associated failed collection statusStringIncorrect collection date
SETTLEMENT_STATUSDThe status of the settlement to the clientStringPENDING
SETTLEMENT_REFERENCEDThe reference for the settlement payment to the client (case-insensitive)StringHJ24GNBZC
TYPEDIndicates the type of DebiCheck. The value can either be RMS or DCStringDC
TOTAL_RECORDSTTotal # of collection items within the fileInteger25
TOTAL_COLLECTION_VALUETTotal value of the collections within the fileDecimal10000.00
TOTAL_COLLECTION_SUCCESS_RECORDSTTotal number of successful collectionsInteger15
TOTAL_COLLECTION_SUCCESS_VALUETTotal value of successful collectionsDecimal7856.00
TOTAL_COLLECTION_FAILED_RECORDSTTotal number of failed collectionsInteger10
TOTAL_COLLECTION_FAILED_VALUETTotal value of failed collectionsDecimal0.00
Sample Output file

Download sample OUTPUT file

Daily files

OUTPUT files will be generated daily. They will include collections that were processed by the end of that specific day, as well as any collections whose settlement statuses have changed. An OUTPUT file can reflect collection results across different collection batches.

Below are the possible collection reason codes that can be received in an OUTPUT file per collection line item:

SUCCESSDPROCESSEDCollection was successful
FAILEDDPAYMENT_SUSPENDEDPayment stopped by account holder
FAILEDDINSUFFICIENT_FUNDSInsufficient funds in the debtors account
FAILEDDAUTHENTICATION_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
FAILEDDDUPLICATE_TRANSACTIONDuplicate transaction identified, there is another transaction already in progress with this consent ID
PENDINGDPENDINGCollection did not go through, but there is still time for it to be actioned and so it should not yet be resubmitted

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

StatusRecord typeDescription
PENDINGDSettlement will be submitted to the bank after funds have been successfully collected from the debtor. No action required.
COMPLETEDDSettlement was successfully submitted, and confirmation was been received by the bank.