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).
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 |
|---|---|---|---|---|
| Reference | H | Collection reference to uniquely identify the collection batch | String | MY_REF |
| Submission date | H | The date the collection was submitted | ISO 8601 | 2023‐08‐31T12:11:20+07:00 |
| ID | D | Collection mandate ID referencing the authorised mandate to collect against | String | bWFuZGF0ZS8zNjljY2RhMS1jZTQ0LTRiMmMtOThhMC05Mjk3ODNmYWY3NTU |
| Value | D | The amount to be collected | Decimal | 3000.00 |
| Tracking period | D | Numeric value indicating how many days from the collection date the account should be tracked for. From 0 up to a maximum of 10 i.e. 1,2,3,..10. Defaults to 0 | Integer | 1 |
| Collection date | D | The collection date in line with what was agreed on in the mandate. Where dateAdjustmentAllowed has been anabled, this date could be different | ISO 8601 | 2023-09-25 |
| Total records | T | Total number of collection items within the file | Integer | 25 |
| Total tracking records | T | Total number of collections with tracking period provided | Integer | 5 |
| Total value | T | The total value of all the collections | Decimal | 10000.00 |
| Total tracking value | T | The total value of all the collection with a tracking period provided | Decimal | 963.1 |
Sample Incoming Collection File
IDis as per the mandate ID sent to you by Stitch once a mandate has been created- Tracking period can only be provided if the "tracking" value is set to
truewhen creating a mandate dateAdjustmentAllowedis 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 it will indicate whether
the collection batch was submitted or not submitted.
Once you have submitted a collection batch file, Stitch will perform 2 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 a 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 |
| ID | In the case of a data validation error, the mandate ID for the collection line item | String | bWFuZGF0ZS8zNjljY2RhMS1jZTQ0LTRiMmMtOThhMC05Mjk3ODNmYWY3NTU= |
| Status | The status result from the validation. Value can only be ERROR | String | bWFuZGF0ZS8zNjljY2RhMS1jZTQ0LTRiMmMtOThhMC05Mjk3ODNmYWY3NTU= |
| 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. When a file fails schema
validation, no collections 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 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.
- 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
REPLYfile.
Formatting Rules
| Field | Rule | Error reason | Description |
|---|---|---|---|
| Reference | Batch reference required | BATCH_REFERENCE_REQUIRED | Missing batch reference |
| Submission date | ISO 8601 format for submission date | INVALID_SUBMISSION_DATE | Invalid submission date provided |
| ID | Format should be a base64 string | INVALID_ID | Invalid ID provided |
| Collection date | ISO 8601 format for date | INVALID_DATE | Invalid date provided |
| Value | Decimal format for value | INVALID_VALUE | Invalid value provided |
| Tracking period | Integer format for tracking period | INVALID_TRACKING_PERIOD | Invalid tracking period provided |
Data rules
| Field | Rule | Error reason | Description |
|---|---|---|---|
| Reference | Batch references should be unique for batches that pass schema validation | DUPLICATE_BATCH_REFERENCE | A batch with this reference already exists |
| ID | ID should match an authorised, active mandate | UNMATCHED_MANDATE | Invalid mandate ID provided |
| Submission date | 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 |
| Tracking period | If this value is > 0, the mandate should have tracking enabled | UNABLE_TO_TRACK | Unable to track on this mandate |
| Tracking period | Value should be >0 and ≤10 | INVALID_TRACKING_PERIOD | Invalid tracking period provided. Tracking period should be between 0 and 10 days |
| 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 records | Should be equal to the total count of the D records with a tracking period >0 | MISMATCHED_TOTAL_TRACKING_RECORDS | Total tracking records does not match the records with tracking period>0 provided |
| Total tracking value | Should be equal to the sum of the value of the D records with a tracking period >0 | MISMATCHED_TOTAL_TRACKING_VALUE | Total tracking value does not match the sum of the value of the details records with tracking period >0 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
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. You will receive this file daily and it will reflect collection outcomes for collections that have been processed by the end of the day.
| Field | Record type | Description | Type | Example value |
|---|---|---|---|---|
| CURRENT_DATE | 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 |
| STATEMENT_REFERENCE | H | Statement reference for the batch. This will correspond with the line item on your bank statement for the settlement. | String | RANDOM_REF |
| REFERENCE | D | The original batch reference, as supplied by you in the Incoming file, that this collection item belongs to | String | MY_COLL_03 |
| ID | D | Mandate ID | String | bWFuZGF0ZS8zNjljY2RhMS1jZTQ0LTRiMmMtOThhMC05Mjk3ODNmYWY3NTU |
| Collection date | D | Date on which the funds are to be collected, in ISO8601 format | ISO 8601 | 2023-09-25 |
| Value | D | Collection value | Decimal | 653.04 |
| Tracking period | D | Numeric 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,..10 | Integer | 3 |
| Status | D | Collection status | String | FAILED |
| Reason | D | Collection status reason for failed collections | String | Incorrect date |
| 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 value | T | Total value of the items to collect on | Decimal | 10000.00 |
| Total success records | T | Total number of successful collections | Integer | 15 |
| Total success value | T | Total value of successful collections | Decimal | 7856.00 |
| Total failed records | T | Total number of failed collections | Integer | 10 |
| Total failed value | T | Total value of failed collections | Decimal | 2254.00 |
| Total tracking records | T | Total number of tracking collections | Decimal | 4 |
| Total tracking value | T | Total value of tracking collections | Decimal | 54.00 |
| Total tracking success | T | Total number of successful tracking collections | Decimal | 3 |
| Total tracking success value | T | Total value of successful tracking collections | Decimal | 14.00 |
| Total tracking failed | T | Total number of failed tracking collections | Decimal | 1 |
| Total tracking failed value | T | Total value of failed tracking collections | Decimal | 40.00 |
Sample Output file
Since you will receive OUTPUT files daily, for collections that were processed by the end of that specific day, it will be the case that the OUTPUT file reflects collection results across different collection batch submissions.
Collection Request Statuses
Below are the possible statuses that can be received in a REPLY file on a batch level, 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 |
Below are the possible statuses that can be received in an OUTPUT file per collection line item:
| Status | Record type | Status code | 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 | REAUTHENTICATION_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 mandate 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 |