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.

Validation

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, 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 type	Description
H	Header record detailing overall information about the collection
D	Data record that contains the collection request details. All other records are metadata
T	Trailer 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:

Field	Record type	Description	Type	Example value
EXTERNAL_BATCH_REFERENCE	H	Client specified reference to uniquely identify a collection batch.	String	MY_REF
SUBMISSION_DATETIME	H	The datetime the collection was submitted	ISO 8601	2023‐08‐31T12:11:20+07:00
EXTERNAL_COLLECTION_REFERENCE	D	Client specified reference to uniquely identify a collection.	ISO 8601	2023‐08‐31T12:11:20+07:00
CONSENT_ID	D	The Payment Consent ID for the authorised mandate to collect against	String	bWFuZGF0ZS8zNjljY2RhMS1jZTQ0LTRiMmMtOThhMC05Mjk3ODNmYWY3NTU
VALUE	D	The amount to be collected	Decimal	3000.00
COLLECTION_DATE	D	The collection date in line with what was agreed on in the mandate. Where dateAdjustmentAllowed has been enabled, this date could be different	ISO 8601	2023-09-25
TOTAL_RECORDS	T	Total number of collection items within the file	Integer	25
TOTAL_VALUE	T	The total value of all the collections	Decimal	10000.00

Sample Incoming Collection File

Download sample incoming file

note

• 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:

• Schema validation to ensure that the file schema is correct.
• Data validation to ensure that the data submitted is valid.

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

Field	Description	Type	Example value
RECORD_TYPE	The type of record it is. Values can be H, D, or T	String	D
LINE	Which line in the file this error pertains to	Integer	4
CONSENT_ID	In the case of a data validation error, the consent ID for the collection line item	String	bWFuZGF0ZS8zNjljY2RhMS1jZTQ0LTRiMmMtOThhMC05Mjk3ODNmYWY3NTU=
VALIDATION_RESULT	The status result from the validation. Value can only be ERROR	String	ERROR
ERROR_CODE	Indicates 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.	String	SCHEMA_VALIDATION_FAILED
ERROR_REASON	Provides detailed information about the error code and reason for the failed schema or data validation.	String	HEADER_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:

Field	Rule	Error reason	Description
Header records	Header record required	HEADER_RECORD_REQUIRED	Header record required
Header records	Validate the titles of the header rows	INVALID_HEADER_RECORD_TITLE	Incorrect header titles provided
Header records	Number of header record fields	INVALID_HEADER_RECORD	Incorrect number of header record fields provided
Data records	Validate the titles of the detail rows	INVALID_DETAIL_RECORD_TITLE	Incorrect detail titles provided
Data records	Number of detail record fields	INVALID_DETAIL_RECORD	Incorrect number of detail record fields provided
Data records	At least one detail record required	DETAIL_RECORD_REQUIRED	Details record required
Trailer records	Validate the titles of the trailer rows	INVALID_TRAILER_RECORD_TITLE	Incorrect trailer titles provided
Trailer records	Trailer record required	TRAILER_RECORD_REQUIRED	Trailer record required
Trailer records	Number of trailer record fields	INVALID_TRAILER_RECORD	Incorrect number of trailer record fields provided
General	Incorrect record type specified in the record type field	INCORRECT_RECORD_TYPE	Incorrect 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

Field	Record type	Rule	Error reason	Description
EXTERNAL_BATCH_REFERENCE	H	Batch reference required	BATCH_REFERENCE_REQUIRED	Missing batch reference
SUBMISSION_DATETIME	H	ISO 8601 format for submission datetime	INVALID_SUBMISSION_DATE	Invalid submission date provided
CONSENT_ID	D	The payment consent ID string	INVALID_ID	Invalid ID provided
COLLECTION_DATE	D	ISO 8601 format for date	INVALID_DATE	Invalid date provided
VALUE	D	Decimal format for value	INVALID_VALUE	Invalid value provided

Data rules

Field	Rule	Error reason	Description
EXTERNAL_BATCH_REFERENCE	Batch references should be unique for batches that pass schema validation	DUPLICATE_BATCH_REFERENCE	A batch with this reference already exists
CONSENT_ID	ID should match an authorised, active mandate	UNMATCHED_MANDATE	Invalid consent ID provided
SUBMISSION_DATETIME	Date must be current date	INVALID_DATE	Invalid date provided
COLLECTION_DATE	Date should match what's on the mandate	INVALID_DATE	Invalid date provided
COLLECTION_DATE	Date should be a date in the future (at least 1 day in the future)	INVALID_DATE	Invalid date provided
VALUE	Value should match what's on the mandate	INVALID_VALUE	Invalid value provided
TOTAL_RECORDS	Should be equal to the total count of the D records	MISMATCHED_TOTAL_RECORDS	Total records does not match total details records provided
TOTAL_VALUE	Should be equal to the sum of the value of the D records	MISMATCHED_TOTAL_VALUE	Total 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:

Status	Record type	Status code	Description
SUBMITTED	H	SUBMITTED	Collection batch has been submitted
NOT_SUBMITTED	H	NOT_SUBMITTED	Collection 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.

Field	Record type	Description	Type	Example value
RECORD_TYPE	H,D,T	Denotes the record type. Either H, T, or D	String	H
CREATED_DATETIME	H	The date on which the OUTPUT file was generated and uploaded to your SFTP Incoming folder, in ISO8601 format	ISO 8601	2023-08-19T12:11:20+07:00
EXTERNAL_BATCH_REFERENCE	D	The client specified batch reference, as it was supplied in the original collection file.	String	MY_COLL_03
EXTERNAL_COLLECTION_REFERENCE	D	The original external collection reference for the collection, as supplied by you in the Incoming file	String	MY_COLL_03
CONSENT_ID	D	The Payment Consent ID	String	bWFuZGF0ZS8zNjljY2RhMS1jZTQ0LTRiMmMtOThhMC05Mjk3ODNmYWY3NTU
COLLECTION_ID	D	The unique ID for the collection	String	ZGUxZGM5NDItMGNkYS00ZDgzLTkxYzctMzY0N2MxODJlNGE5
COLLECTION_DATE	D	Date on which the funds were collected, in ISO 8601 format	ISO 8601	2023-09-25
VALUE	D	Collection value	Decimal	653.04
COLLECTION_STATUS	D	The status of the collection from the debtor	String	FAILED
COLLECTION_REASON	D	Reason for the associated failed collection status	String	Incorrect collection date
SETTLEMENT_STATUS	D	The status of the settlement to the client	String	PENDING
SETTLEMENT_REFERENCE	D	The reference for the settlement payment to the client (case-insensitive)	String	HJ24GNBZC
TYPE	D	Indicates the type of DebiCheck. The value can either be RMS or DC	String	DC
TOTAL_RECORDS	T	Total # of collection items within the file	Integer	25
TOTAL_COLLECTION_VALUE	T	Total value of the collections within the file	Decimal	10000.00
TOTAL_COLLECTION_SUCCESS_RECORDS	T	Total number of successful collections	Integer	15
TOTAL_COLLECTION_SUCCESS_VALUE	T	Total value of successful collections	Decimal	7856.00
TOTAL_COLLECTION_FAILED_RECORDS	T	Total number of failed collections	Integer	10
TOTAL_COLLECTION_FAILED_VALUE	T	Total value of failed collections	Decimal	0.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:

COLLECTION_STATUS	RECORD_TYPE	COLLECTION_REASON	Description
SUCCESS	D	PROCESSED	Collection was successful
FAILED	D	PAYMENT_SUSPENDED	Payment stopped by account holder
FAILED	D	INSUFFICIENT_FUNDS	Insufficient funds in the debtors account
FAILED	D	AUTHENTICATION_REQUIRED	Mandate needs to be re-authenticated
FAILED	D	BANK_ERROR	A system error occurred at the bank
FAILED	D	BANK_PROCESSING_ERROR	Creditor bank unable to process due to problem
FAILED	D	INACTIVE_ACCOUNT	Account frozen, account in liquidation, account closed, or account holder deceased
FAILED	D	INVALID_ACCOUNT	Debits not allowed on this account, account not found, or debtor account number fails CDV routine
FAILED	D	BENEFICIARY_BANK_PROCESSING_ERROR	Creditor bank unable to process due to problem
FAILED	D	MANDATE_SUSPENDED	Mandate is suspended
FAILED	D	INVALID_USER_REGISTRATION	User not correctly registered
FAILED	D	DUPLICATE_TRANSACTION	Duplicate transaction identified, there is another transaction already in progress with this consent ID
PENDING	D	PENDING	Collection 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:

Status	Record type	Description
PENDING	D	Settlement will be submitted to the bank after funds have been successfully collected from the debtor. No action required.
COMPLETED	D	Settlement was successfully submitted, and confirmation was been received by the bank.