Collections

Card Collections facilitates batch processing of recurring payments using pre-tokenised credentials securely stored in Stitch Vault. View the documentation for more information on tokenising card funding details and token management.

Initiating Requests via SFTP

The diagram outlines the high-level flow for initiating requests using a COLLECTION file. The outcome of the collection request is a REPLY file and an OUTPUT file. The REPLY file contains the validation and submission results obtained from processing the COLLECTION file. The OUTPUT file indicates the status of each record in the COLLECTION file.

The COLLECTION file must contain a reference to each tokenised credential to be used for the recurring payment charge and relevant payer agreement information.

SFTP Connection

An SFTP server is used to upload COLLECTION files and receive REPLY and OUTPUT files from Stitch.

Stitch will configure your SFTP credentials during the onboarding process. Files can be submitted once access and connectivity has been configured successfully.

SFTP Directory Structure

An SFTP user will be provisioned and granted access to a specific SFTP directory. The user has access to Incoming, Outgoing and Archive folders.

The directory structure is as follows:

Folder Description
/	Root folder
/Incoming	Contains incoming files to be consumed. REPLY files OUTPUT files
/Outgoing	Contains outgoing files to be processed. COLLECTION files Corrected COLLECTION files
/Archive	Files will be archived regularly. This is the Archive directory root and it's structure will mimic the root-level (/) structure.
/Archive/Outgoing	The Archive subdirectory containing archived outgoing files
/Archive/Incoming	The Archive subdirectory containing archived incoming files

File Archival

Files are archived to the Archive directory at a regular cadence.

• COLLECTION files that are uploaded in the Outgoing subdirectory will be archived once they are processed.
• REPLY and OUTPUT files in the Incoming subdirectory will be archived every 30 days.

File Types and Validation

Card Collections uses three CSV file types: COLLECTION, REPLY and OUTPUT. Each file contains four possible record types. Each record type is described in the table 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 a CSV file containing a reference to credentials to charge. This file is required to process collections. The COLLECTION file schema is as follows:

Record Type	Field	Type	Description
-	RECORD_TYPE	string	Indicates the record type. Possible values: P, H, D, T
P	CLIENT_ID	string	The Stitch Client ID
P	PRODUCT	string	Indicates the product type. Must be set to CARD.
P	FILE_TYPE	string	Specifies the type of file being submitted. Must be COLLECTION.
H	SUBMISSION_DATETIME	string	The file submission timestamp in ISO8601 format.
H	BATCH_REFERENCE	string	A client-defined reference for the collection request batch.
D	TOKEN	string	The card credential token reference.
D	NONCE	string	A unique nonce used to ensure idempotency of the request.
D	QUANTITY	numeric	The amount in ZAR to charge
D	AGREEMENT_REFERENCE	string	A reference to the payer's collection agreement with the client.
D	AGREEMENT_VARIABILITY	string	Possible values: fixed or variable.
D	AGREEMENT_EXPIRE_AT	string	The timestamp at which agreement is no longer valid in ISO8601 format.
D	COLLECTION_DATE	string (optional)	A future date for collection. Collections are processed immediately by default.
D	EXTERNAL_REFERENCE	string (optional)	A custom reference associated with each collection submission.
D	PAYER_ID	string (optional)	An internal identifier for the payer.
D	MOBILE_NUMBER	string (optional)	The payer's contact number.
D	EMAIL	string (optional)	The payer's email address.
D	FULL_NAME	string (optional)	The payer's full name.
T	TOTAL_RECORDS	numeric	The total number of individual collection records in the batch.
T	TOTAL_QUANTITY	numeric	The total amount for all collection records in the batch.

Sample COLLECTION File

Reply File

The REPLY file contains validation results related to the submission request and indicates which records were processed successfully or require correction and re-submission. Stitch performs two types of validation on the COLLECTION file:

• Schema Validation is applied to ensure that the file structure conforms to the schema
• Data Validation is applied to ensure the submitted data is not malformed and contains permissible values

Validation

Stitch includes validation and submission results in the REPLY file. Invalid D records must be corrected and re-submitted. A new COLLECTION file must be submitted that contains only invalid D records.

The REPLY file is sent as an acknowledgement if no validation errors are contained in the COLLECTION file.

The REPLY file schema is as follows:

Record Type	Field	Type	Description
-	RECORD_TYPE	string	Indicates the record type. Possible values: P, H, D, T
P	CLIENT_ID	string	The Stitch Client ID.
P	PRODUCT	string	Indicates the product type. Set to CARD.
P	FILE_TYPE	string	Specifies the type of file being submitted. Set to COLLECTION.
D	LINE	numeric	The COLLECTION file line number
D	TOKEN	string	The card credential token reference.
D	AGREEMENT_REFERENCE	string	A reference to the payer's collection agreement with the client.
D	STATUS	string	The validation result of the individual collection item.
D	STATUS_CODE	string	Possible values: SCHEMA_VALIDATION_FAILED or DATA_VALIDATION_FAILED.
D	STATUS_REASON	string	A code indicating the specific validation issue, e.g. INVALID_QUANTITY.
T	TOTAL_RECORDS	numeric	The total number of individual collection records in the batch.

Schema Validation

Validation is performed to ensure that the submitted COLLECTION file conforms to the expected schema. A validation failure results in a SCHEMA_VALIDATION_FAILED error reason in the REPLY file Header (H) record and, where possible, the data records that failed schema validation.

The table below enumerates the possible values for the STATUS_REASON in the case of a failure. The STATUS_REASON is indicative of the failure cause.

Record Type	Status Reason
P	PRODUCT_HEADER_RECORD_REQUIRED
P	INVALID_PRODUCT_HEADER_RECORD
P	INVALID_PRODUCT_HEADER_RECORD_TITLE
H	HEADER_RECORD_REQUIRED
H	INVALID_HEADER_RECORD_TITLE
H	INVALID_HEADER_RECORD
D	INVALID_DATA_RECORD_TITLE
D	INVALID_DATA_RECORD
D	DATA_RECORD_REQUIRED
T	INVALID_TRAILER_RECORD_TITLE
T	TRAILER_RECORD_REQUIRED
T	INVALID_TRAILER_RECORD
—	INCORRECT_RECORD_TYPE

Data Validation

Validation is performed on Data (D) records contained in 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 results in a DATA_VALIDATION_FAILED status code in the REPLY file header with each data validation status reason appearing alongside each collection row.

Validation Failures

• If the Product Header (P) or Header (H) records fail data validation, the collection batch is not processed. The corresponding REPLY file contains validation results only for the P and/or H records.
• If the P and H records pass data validation but a subset of D records fail validation, the valid records will be submitted for processing.
• The D records that fail data validation are returned for correction and resubmission in the REPLY file with a status of FAILED. D records that pass data validation are included with status SUCCESS.
• Multiple validation results for the same line can be returned in the REPLY file. This implies that multiple REPLY records can reference the same COLLECTION record.

Example
This is example REPLY file corresponds to a COLLECTION file with one valid D record and two invalid D records. The valid collection is submitted for processing.

| RECORD_TYPE     | CLIENT_ID                              | PRODUCT                                                          | FILE_TYPE              |             |                          |                                  |
|-----------------|----------------------------------------|------------------------------------------------------------------|------------------------|-------------|--------------------------|----------------------------------|
| P               | bf482d8d-0423-4a77-937b-a5b4d75bd734   | REPLY                                                            | REPLY                  |             |                          |                                  |
| --------------- | -------------------------------------- | ---------------------------------------------------------------- | ---------------------- | ----------- | ------------------------ | -------------------------------- |
| RECORD_TYPE     | LINE                                   | TOKEN                                                            | AGREEMENT_REFERENCE    | STATUS      | STATUS_CODE              | STATUS_REASON                    |
| --------------- | -------------------------------------- | ---------------------------------------------------------------- | ---------------------- | ----------- | -----------------------  | -------------------------------- |
| D               | 6                                      | dG9rZW4vMTQ0NjZlYjAtMjlhMi00ZDM3LWIyYjctNTZkMWFkNWIxZWIw         | AGR_001                | FAILED      | DATA_VALIDATION_ERROR    | INVALID_QUANTITY                 |
| D               | 7                                      | dG9rZW4vMTQ0NjZlYjAtMjlhMi00ZDM3LWIyYjctNTZkMWFkNWIxZWIy         | AGR_002                | FAILED      | DATA_VALIDATION_ERROR    | INVALID_NONCE                    |
| D               | 8                                      | dG9rZW4vMTQ0NjZlYjAtMjlhMi00ZDM3LWIyYjctNTZkMWFkNWIxZWIz         | AGR_003                | SUCCESS     |                          |                                  |
| --------------- | -------------------------------------- | ---------------------------------------------------------------- | ---------------------- | ----------- | ------------------------ | -------------------------------- |
| RECORD_TYPE     | TOTAL_RECORDS                          |                                                                  |                        |             |                          |                                  |
| --------------- | -------------------------------------- | ---------------------------------------------------------------- | ---------------------- | ----------- | ------------------------ | -------------------------------- |
| T               | 3                                      |                                                                  |                        |             |                          |                                  |

Sample REPLY File

Output File

Stitch processes valid collection submissions. A final OUTPUT is compiled containing the collection results once processing is complete.

Record Type	Field	Type	Description
-	RECORD_TYPE	string	Indicates the record type. Possible values: P, H, D, T
P	CLIENT_ID	string	The Stitch Client ID.
P	PRODUCT	string	Indicates the product type. Set to CARD.
P	FILE_TYPE	string	Specifies the type of file being submitted. Set to COLLECTION.
D	STITCH_ID	string	The Stitch-generated identifier for the transaction.
D	NONCE	string	A unique nonce used to ensure idempotency of the request.
D	QUANTITY	numeric	The amount in ZAR that was charged.
D	AGREEMENT_REFERENCE	string	A reference to the payer's collection agreement with the client.
D	COLLECTION_DATE	string	The date on which the collection occurred, in ISO8601 format.
D	EXTERNAL_REFERENCE	string (optional)	A custom reference associated with each collection submission.
D	STATUS	string	The resulting status of the collection transaction.
D	STATUS_REASON	string	The transaction status reason.
D	RETRIEVAL_REFERENCE_NUMBER	string (optional)	The Retrieval Reference Number (RRN) assigned to the transaction.
D	RETRYABLE	boolean	Indicates whether the collection can be retried.
T	TOTAL_RECORDS	numeric	The total number of transaction records in the batch.
T	TOTAL_QUANTITY	numeric	The total amount across all transaction records in the batch.
T	TOTAL_SUCCESS_RECORDS	numeric	The number of transactions that completed successfully.
T	TOTAL_SUCCESS_QUANTITY	numeric	The total amount for all successful transactions.
T	TOTAL_FAILURE_RECORDS	numeric	The number of transactions that failed.
T	TOTAL_FAILURE_QUANTITY	numeric	The total amount for all failed transactions.

Sample OUTPUT File

Transaction Statuses

The table below describes the different STATUS values a transaction can have, within an output file response:

Status	Description
TransactionSuccess	The transaction has been successfully completed, and user's card has been charged.
TransactionFailure	The transaction failed to be charged on the user's card. An associated STATUS_REASON will be returned with this status.

Failure Reasons

The TransactionFailure status indicates that the card transaction failed to be initiated, and includes a STATUS_REASON explaining the cause.

Potential failure reasons are detailed below:

Reason	Description
authorizationFailed	The transaction was declined or blocked.
authorizationNotFinalised	The transaction could not be processed by the acquirer.
blockedByFraudChecks	The transaction was blocked due to fraud checks.
downstreamProviderError	The transaction could not be processed due to downstream error.
exceedsCardWithdrawalLimit	The transaction was declined due to withdrawal limits exceeded.
insufficientFunds	The transaction was declined due to insufficient funds.
internalServerError	The transaction could not be processed due to a server error.
invalidCardError	The transaction was declined due to an expired card.
invalidConfigurationError	The client has invalid or missing configuration.
invalidTransactionError	The transaction could not be processed due to invalid data.
tokenDecryptionError	The payment token could not be decrypted.

File Naming Conventions

Outgoing

Outgoing files are sent to Stitch via the SFTP server.

Follow the outlined naming conventions for requests initiated via SFTP. Files are dropped in the Outgoing directory.
The complete file name is: <product>/<datetime>_<index>.csv.

• product is CARD
• datetime is the current Datetime in ISO format excluding special characters and non-numeric characters, for example, 202401011200560123
• index is an index generated and appended to the file name. This index is used for duplicate prevention The index must start at 0 and be incremented by 1 with each submission. There is no limit to the size of this index.

An example file name is CARD/202401011200560123_1.csv

Incoming

Incoming files are received from Stitch and are located in the Incoming directory.
The complete file name is: <product>/<datetime>_<fileType>.csv.

• product is CARD
• datetime is the current Datetime in ISO format excluding special characters and non-numeric characters, for example, 202401011200560123
• fileType is the file type that you are receiving. This will be either REPLY or OUTPUT.

An example file name is CARD/202401011200560123_OUTPUT.csv

note

• The product value corresponds with the PRODUCT value in the Product Header (P) record
• The fileType value corresponds with the FILE_TYPE value in the Product Header (P) record

Test Scenarios

Different failure scenarios can be simulated using specific tokens within a collection when using a test client. The table below enumerates the mapping between tokens and the resulting transaction status reason.

Token	Status	Reason
dG9rZW4tY2FyZC9iZjVlNGQ4NS0wZjBlLTQ5ZDgtOGZlZS0zZjAzNjEyMDZiODA=	TransactionFailure	authorizationFailed
dG9rZW4tY2FyZC84OTQ5ZTIxNS02NTc1LTQzNzMtOTM1ZC1hNzExZTdmNWU3MzU=	TransactionFailure	insufficientFunds
dG9rZW4tY2FyZC9mOGU1N2NjMS0xMWIxLTRmZmItOTU4NS0yZjAxZDBmNmRmMWU=	TransactionFailure	downstreamProviderError
dG9rZW4tY2FyZC81OTkzM2RjOS01ZjdkLTRiNGMtYjQyOS1lZWI4MWIzMjY1YzA=	TransactionSuccess	-