Debit Order Collection Files

In order to process debit order 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.

note

A collection initially marked with a status of SUCCESS may later be followed by an UNPAID record in a subsequent OUTPUT file.

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 3 collections and 2 failed validation, Stitch will notify you via a REPLY file like the example below:

| Record type   | CLIENT_ID                            | PRODUCT                  | CHANNEL                       | FILE_TYPE          |
|---------------|--------------------------------------|--------------------------|-------------------------------|--------------------|
| P             | bf482d8d-0423-4a77-937b-a5b4d75bd734 | COLLECTIONS              | DEBIT ORDER                   | REPLY              |
|---------------|--------------------------------------|--------------------------|-------------------------------|--------------------|-----------|-----------------------|----------------------------|
| Record type   | LINE                                 | EXTERNAL_BATCH_REFERENCE | EXTERNAL_COLLECTION_REFERENCE | CONTRACT_REFERENCE | STATUS    | STATUS_CODE           | STATUS_REASON              |
|---------------|--------------------------------------|--------------------------|-------------------------------|--------------------|-----------|-----------------------|----------------------------|
| D             | 6                                    | Batch_reference_1        | COLLECTION_REF_1              | CONTRACT_REF_1     | FAILED    | DATA_VALIDATION_ERROR | INVALID_BRANCH_CODE          |
| D             | 7                                    | Batch_reference_1        | COLLECTION_REF_2              | CONTRACT_REF_2     | FAILED    | DATA_VALIDATION_ERROR | DUPLICATE_COLLECTION_NONCE |
| D             | 8                                    | Batch_reference_1        | COLLECTION_REF_3              | CONTRACT_REF_3     | SUCCESS   |                       |                            |
|---------------|--------------------------------------|--------------------------|-------------------------------|--------------------|-----------|-----------------------|----------------------------|
| Record type   | TOTAL RECORDS                        |
|---------------|--------------------------------------|
| T             | 3                                    |

The successful collection on line 8 will have been processed, while the other two collections that failed validation must be resubmitted as a new batch once the issues have been rectified.

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 DEBIT ORDER	String	DEBIT ORDER
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
EXTERNAL_COLLECTION_REFERENCE required	D	Client specified reference to uniquely identify a collection. (Maximum permissible length: 4096 characters)	String	MY_COLL_01
VALUE required	D	The amount to be collected	Decimal	3000.00
COLLECTION_DATE required	D	The collection date for the debit order.	ISO 8601	2023-09-25
CONTRACT_REFERENCE required	D	Contract reference for the authorised mandate as specified on the Payment Consent.	String	MY_CONTRACT_REF
DEBTOR_NAME required	D	The name on the account of the debtor for the collection	String	John Doe
DEBTOR_ACCOUNT_NUMBER required	D	The account number to be collected from	Integer	97834567890
DEBTOR_BRANCH_CODE required	D	The branch code for the account number supplied	Integer	050001
DEBTOR_ACCOUNT_TYPE required	D	The debtor's account type. Possible values are Current, Savings, Transmission, Bond and Subscription	String	Current
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

Sample Incoming Debit Order Collection File

Download sample incoming file

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
EXTERNAL_BATCH_REFERENCE	In the case of a data validation error, the batch reference of the incoming collection file	String	MY_BATCH_01
EXTERNAL_COLLECTION_REFERENCE	In the case of a data validation error, the collection reference for the collection line item	String	MY_COLL_01
CONTRACT_REFERENCE	In the case of a data validation error, the Contract reference for the collection line item	String	MY_CONTRACT_REF
STATUS	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.

Formatting and Data Validation Rules for header, product header and trailer record

Field	Record type	Rule	Status reason	Description
CLIENT_ID	P	Client ID as provided during onboarding	INVALID_CLIENT_ID	Provided Client ID doesn't match expected Client ID
PRODUCT	P	Always COLLECTIONS	INVALID_PRODUCT	Unexpected product provided
FILE_TYPE	P	Always COLLECTION	INVALID_FILE_TYPE	Invalid file type provided
CHANNEL	P	Always DEBIT ORDER	INVALID_CHANNEL	Invalid channel provided
EXTERNAL_BATCH_REFERENCE	H	Batch references should be unique for batches that pass schema validation	DUPLICATE_BATCH_REFERENCE	A batch with this reference already exists
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
TOTAL_RECORDS	T	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	T	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

Example Invalid Reply File

Download sample REPLY file - Schema validation failure

Schema Validation failure

• If the product header or header records of a collection file fail schema validation, the remainder of the collection file is not processed. The corresponding REPLY file may contain only validation results for the P and H records, omitting validation results for D records.
• Multiple validation results for the same line may be present in the REPLY file, so there may be multiple lines referencing the same line in the collection file.

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.

Formatting Rules for data record

Field	Record type	Rule	Status reason	Description
Data records	D	At least one detail record required	DETAIL_RECORD_REQUIRED	Details record required
EXTERNAL_COLLECTION_REFERENCE	D	Collection reference required	INVALID_VALUE	Missing collection reference
NONCE	D	Unique nonce required	INVALID_VALUE	Missing nonce
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
DEBTOR_NAME	D	Debtor name is required	INVALID_VALUE	Missing debtor name
DEBTOR_ACCOUNT_NUMBER	D	Debtor account number is required	INVALID_VALUE	Missing account number
DEBTOR_BRANCH_CODE	D	Debtor branch code is required	INVALID_VALUE	Missing branch code
DEBTOR_ACCOUNT_TYPE	D	Debtor account type is required	INVALID_VALUE	Missing account type

Data rules

Field	Rule	Status reason	Description
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
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 (configured during onboarding).	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
DEBTOR_NAME	Permitted upto 35 characters long.	INVALID_NAME	Account name has incorrect length
DEBTOR_ACCOUNT_NUMBER	Should be a vaild account number.	INVALID_ACCOUNT	Invalid account number
DEBTOR_ACCOUNT_NUMBER	Should be a valid branch code.	INVALID_BRANCH_CODE	Invalid branch code provided
DEBTOR_ACCOUNT_TYPE	Should be a valid account type. One of Current, Savings, Transmission, Bond and Subscription	INVALID_ACCOUNT_TYPE	Invalid branch code 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

Data Validation failure

• If the product header or header records of a collection file fail data validation, the remainder of the collection is not processed. The corresponding REPLY file may contain only validation results for the P and H records, omitting validation results for D records.
• If the product header and header records of a collection file pass data validation, but some 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 with a status of FAILED. Any data records that passed data validation will also be included with a status of SUCCESS.
• Multiple validation results for the same line may be present in the REPLY file, so there may be multiple lines referencing the same line in the collection file.

Output File

An OUTPUT file will be used to inform you of the collection results for all the valid collections that were submitted. 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 DEBIT ORDER	String	DEBIT ORDER
FILE_TYPE	P	Type of file indicating what contents should be expected. This will be either REPLY, OUTPUT, DISPUTE	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
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
BANK_CODE	D	Underlying bank response code for the collection	String	900001
BANK_CODE_DESCRIPTION	D	Underlying bank response description for the collection	String	Mandate is Suspended
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
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

Sample Output file

Download sample OUTPUT file - OUTPUT 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	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, account holder deceased or account in sequesterian
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	INVALID_BRANCH_CODE	Branch code is invalid
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 reversed 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.

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.

Testing Collection Scenarios

When submitting collections using your test client, certain amounts can be specified as the collection amount in the outgoing collection file to simulate different collection success and failure scenarios. These scenarios will be reported in the output file.

The table below shows the supported amounts, status and collection reason mappings:

Amount	Status	Collection reason
70.00-79.99	FAILED	INVALID_BRANCH_CODE
60.00-69.99	FAILED	BENEFICIARY_BANK_PROCESSING_ERROR
50.00-59.99	FAILED	INVALID_ACCOUNT
40.00-49.99	FAILED	INACTIVE_ACCOUNT
30.00-39.99	FAILED	BANK_PROCESSING_ERROR
20.00-29.99	FAILED	BANK_ERROR
10.00–19.99	FAILED	INSUFFICIENT_FUNDS
0.01–9.99	FAILED	PAYMENT_SUSPENDED
Other	SUCCESS	PROCESSED

Note:

This only applies to test clients.