Collection Files

In order to process collections, you will be required to upload collection files to Stitch's SFTP server. 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 collection items being processed and the failed collection items and their 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 containing all collection items being processed.

File Types and Validation

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

Record type	Description
P	Product Header record detailing client ID, product information and file type
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

Outgoing 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
CLIENT_ID	P	Client ID as issued during onboarding	UUID	399a7ed1-0617-40f1-a9b7-d66f07b3a29d
PRODUCT	P	Product that the file is for. In this case, it will always be COLLECTIONS	String	COLLECTIONS
CHANNEL	P	Channel within a specific product that the file is for. This will always be DEBICHECK	String	DEBICHECK
FILE_TYPE	P	Type of file indicating what contents should be expected. This will be COLLECTION	String	COLLECTION
EXTERNAL_BATCH_REFERENCE required	H	Client specified reference to uniquely identify a collection batch. (Maximum permissible length: 4096 characters)	String	MY_REF
SUBMISSION_DATETIME required	H	The datetime the collection was submitted.	ISO 8601	2023‐08‐31T12:11:20+07:00
NONCE required	D	A unique string per collection request. (Minimum permissible length: 8 characters. Maximum permissible length: 36 characters)	String	14lji0cpjloigq
CONTRACT_REFERENCE required	D	Contract reference for the authorised mandate as specified on the Payment Consent.	String	MY_CONTRACT_REF
EXTERNAL_COLLECTION_REFERENCE required	D	Client specified reference to uniquely identify a collection. (Maximum permissible length: 4096 characters)	String	MY_COLL_01
CONSENT_ID required	D	The Payment Consent ID for the authorised mandate to collect against	String	bWFuZGF0ZS8zNjljY2RhMS1jZTQ0LTRiMmMtOThhMC05Mjk3ODNmYWY3NTU
VALUE required	D	The amount to be collected	Decimal	3000.00
COLLECTION_DATE required	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
TRACKING_PERIOD	D	The number of days a collection needs to be tracked. Only required if, tracking was enabled at the time of mandate initiation. Value should be between 0 to 10	Integer	1
TOTAL_RECORDS required	T	Total number of collection items within the file	Integer	25
TOTAL_VALUE required	T	The total value of all the collections	Decimal	10000.00
TOTAL_TRACKING_RECORDS	T	Total number of collection items which have tracking enabled within the file	Integer	1
TOTAL_TRACKING_VALUE	T	The total value of all the collections which have tracking enabled within the file	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 REPLY file communicates the outcome of all of the entries within the submitted collection file, both successes and failures.

Field	Description	Type	Example value
RECORD_TYPE	The type of record it is. Values can be P, 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=
CONTRACT_REFERENCE	Contract reference for the authorised mandate as specified on the Payment Consent	String	MY_CONTRACT_REF
VALIDATION_RESULT	The status result from the validation. Value can be SUCCESS and FAILED	String	FAILED
STATUS_CODE	Indicates whether the collection was submitted or not. In the case that it wasn't, indicates why the collection was not submitted. In the case of failure, the code can be either SCHEMA_VALIDATION_FAILED or DATA_VALIDATION_FAILED.	String	SCHEMA_VALIDATION_FAILED
STATUS_REASON	Provides detail information about the STATUS_CODE	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 STATUS_REASON in the case of a failure, indicating which part of the schema failed validation:

Field	Rule	Status reason	Description
Product Header records	Product Header record required	PRODUCT_HEADER_RECORD_REQUIRED	Product Header record required
Product Header records	Number of header record fields	INVALID_PRODUCT_HEADER_RECORD	Incorrect number of product header record fields provided
Product Header records	Validate the titles of the product header rows	INVALID_PRODUCT_HEADER_RECORD_TITLE	Incorrect product header titles provided
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 status code in the REPLY file header with each data validation status reason appearing alongside each collection row.

Validation failure

• If the product 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 fails data validation, the entire collection file will not be processed!
• If the product header and header record of a collection file pass 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	Status 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
EXTERNAL_COLLECTION_REFERENCE	D	Collection reference required	INVALID_VALUE	Missing collection reference
NONCE	D	Unique nonce required	INVALID_VALUE	Missing nonce
CONSENT_ID	D	The payment consent ID string	INVALID_ID	Invalid ID provided
CONTRACT_REFERENCE	D	Contract reference required	INVALID_VALUE	Missing contract reference
COLLECTION_DATE	D	ISO 8601 format for date	INVALID_COLLECTION_DATE	Invalid date provided
VALUE	D	Decimal format for value	INVALID_VALUE	Invalid value provided

Data rules

Field	Rule	Status reason	Description
CLIENT_ID	Client ID as provided during onboarding	INVALID_CLIENT_ID	Provided Client ID doesn't match expected Client ID
PRODUCT	Always COLLECTIONS	INVALID_PRODUCT	Unexpected product provided
FILE_TYPE	Always COLLECTION	INVALID_FILE_TYPE	Invalid file type provided
CHANNEL	Always DEBICHECK	INVALID_CHANNEL	Invalid channel provided
EXTERNAL_BATCH_REFERENCE	Batch references should be unique for batches that pass schema validation	DUPLICATE_BATCH_REFERENCE	A batch with this reference already exists
CONTRACT_REFERENCE	Contract reference should correspond to an existing Payment Consent	INVALID_CONTRACT_REFERENCE	Contract reference does not match with an existing, GRANTED consent request
SUBMISSION_DATETIME	Date must be current date	INVALID_SUBMISSION_DATE	Invalid submission date provided
NONCE	Nonce should be unique per collection	INVALID_NONCE	Collection with this nonce already exists or has incorrect length
CONSENT_ID	ID should match an authorised mandate	UNMATCHED_MANDATE	Invalid consent ID provided
CONSENT_ID	ID should match an active mandate	INACTIVE_MANDATE	Invalid consent ID provided. Consent is in a status other than GRANTED
COLLECTION_DATE	Date should match what's on the mandate	INVALID_COLLECTION_DATE	Invalid collection date provided
COLLECTION_DATE	Date should be a date in the future (at least 3 days in the future)	INVALID_COLLECTION_DATE	Invalid collection date provided
COLLECTION_DATE	Date should match the frequency and day as per mandate.	INVALID_COLLECTION_DATE	Invalid collection date provided
COLLECTION_DATE	Only one collection attempt can be created per mandate cycle.	DUPLICATE_COLLECTION_ACTION_DATE	Collection with same collection date already exists
VALUE	Value should match what's on the mandate	INVALID_VALUE	Invalid value provided
TRACKING_PERIOD	Value should be between 0 to 10.	INVALID_TRACKING_PERIOD	Invalid tracking period provided. Tracking period should be between 0 and 10 day
TRACKING_PERIOD	Only to be passed if tracking was enabled while mandate initiation.	UNABLE_TO_TRACK	Unable to track on this mandate
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
TOTAL_TRACKING_VALUE	Should be equal to the sum of the value of the D records where tracking_period is provided	MISMATCHED_TOTAL_TRACKING_VALUE	Total tracking value does not match the sum of the value of the details records with tracking period > 0 provided
TOTAL_TRACKING_RECORDS	Should be equal to the sum of the total count of the D records where tracking_period is provided	MISMATCHED_TOTAL_TRACKING_RECORDS	Total tracking records do not match the records with tracking period >0 provided

Sample Reply File

Download sample REPLY file - Data validation failure for the product header

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. 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	P,H,D,T	Denotes the record type. Either P,H,D or T	String	D
CLIENT_ID	P	Client ID as issued during onboarding	UUID	399a7ed1-0617-40f1-a9b7-d66f07b3a29d
PRODUCT	P	Product that the file is for. In this case, it will always be COLLECTIONS	String	COLLECTIONS
CHANNEL	P	Channel within a specific product that the file is for. This will always be DEBICHECK	String	DEBICHECK
FILE_TYPE	P	Type of file indicating what contents should be expected. This will be either REPLY, OUTPUT, DISPUTE, SETTLEMENT	String	REPLY
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
CONTRACT_REFERENCE	D	Contract reference of the mandate	String	contractRefernce1
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
TOTAL_COLLECTION_PENDING_RECORDS	T	Total number of collections in pending state	Integer	2
TOTAL_COLLECTION_PENDING_VALUE	T	Total value of collections in pending state	Decimal	0.00
TOTAL_COLLECTION_DISPUTED_RECORDS	T	Total number of disputed collections (Only in case of DISPUTE file)	Integer	2
TOTAL_COLLECTION_DISPUTED_VALUE	T	Total value of disputed collections (Only in case of DISPUTE file)	Decimal	100.00

Sample Output file

Download sample OUTPUT file - OUTPUT file type

Download sample OUTPUT file - DISPUTE file type

Download sample OUTPUT file - SETTLEMENT file type

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 has been submitted to partner bank for collection and will be actioned on collection date
DISPUTED	D	DISPUTED	Collection has been disputed by the customer and has been refunded by the bank. Amount will be deducted from the settlement.

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.
SUCCESS	D	Settlement was successfully submitted, and confirmation has been received by the bank.

File naming

Outgoing

These are files you send to Stitch.

In order to easily distinguish between different files, you will be required to follow the below naming conventions for any files you send to Stitch via SFTP. You will be placing your files in the Collections folder.
The complete file name will be : <product>/<datettime>_<index>.csv.

Where:

• product is always Collections
• datetime is the current Datetime in ISO format excluding special characters and non-numeric characters, for example, 202401011200560123
• index is an index generated by you to append to the end of the file name. This index ensures uniqueness across the files and should start at 0 and be incremented by 1 with each submission. There is no limit to the size of this index. No two indexes can be the same.

An example of this file name would be Collections/202401011200560123_1.csv

Incoming

These are files you can expect to receive from Stitch.

You wil receive files with the following naming convention, in your Collections folder. The complete file name will be: <product>/<datettime>_<fileType>.csv.

Where:

• product is always Collections
• datetime is the current Datetime in ISO format without special characters i.e. 202401021200560123
• fileType is the file type that you are receiving. This will be either REPLY or OUTPUT.

An example of this file name would be Collections/202401011200560123_OUTPUT.csv

note

• The product value corresponds with the PRODUCT value provided within the file as a part of the Product Header
• The fileType value corresponds with the FILE_TYPE value provided within the file as a part of the Product Header

Collections Folder

Your files must be placed in the Collections folder. If your files aren't placed here, they will not be picked up.