Upload methods
API integration (real-time)
Connect your system directly to Loyalife’s Transaction API to submit events as they occur. The Rule Engine evaluates and awards points immediately after each submission. When to use API integration:- Your program requires near-instant point updates after a purchase
- Members expect to see their balance update right after a transaction
- Your platform already has API capabilities
Batch processing (file upload)
Data accumulates over a defined period and is processed in bulk at scheduled intervals. Files are transferred via SFTP to the Loyalife server. When to use batch processing:- Your source system already exports transaction logs on a schedule (end of day, hourly, etc.)
- Near-real-time updates are not required by your program
- You are migrating a large historical transaction dataset
SFTP file upload
Obtain SFTP credentials
Request your program-specific SFTP credentials from your Loyalife administrator. These credentials are unique per program.
Connect via VPN
SFTP access is VPN-restricted. Connect to your approved VPN before attempting the SFTP connection.
Upload to the correct directory
Connect to the SFTP server and upload your file to the appropriate directory based on file type:
| File type | Upload path |
|---|---|
| Transaction file (TXN) | upload/TXN |
| Customer profile data (CPD) | upload/CPD |
| Bonus file (BNS) | upload/BNS |
| Card reference data (CRD) | upload/CRD |
File types and formats
Loyalife supports four file types for batch data ingestion. All files are CSV or pipe-delimited depending on program configuration.TXN — transaction file
The TXN file submits purchase or activity transactions for points evaluation by the Rule Engine. The columns included in a TXN file are fully customisable — whatever fields the client’s source system can export are defined as global attributes or custom attributes in Loyalife, and those values are ingested and stored against each transaction.CPD — customer profile data file
The CPD file updates member profile information — used when member data is managed in an external system and synced to Loyalife in bulk. The fields included are customisable per program: any member attributes the client wants to maintain in Loyalife are defined as global or custom attributes, and the CPD file carries those values in on each sync.BNS — bonus file
The BNS file credits bonus points outside of the standard transaction-to-rule evaluation flow. It is used for manual bonus awards, promotional grants, or migration of historical balances. Like other file types, the columns are configurable and map to the attributes defined for your program.BNS entries bypass the Rule Engine — points are credited directly without evaluating IF/THEN conditions. Use BNS for direct awards only; use TXN files when you want the Rule Engine to calculate the correct point amount from a transaction.BNS file uploads post as Credit By Bonus entries on the member’s ledger. If the BNS file is used for a balance migration or inbound transfer from an external programme, the entries may alternatively appear as Credit Transfer. Both are filterable in Transactional reports under Reports & Analytics → Transaction Category.
CRD — card reference data file
The CRD file links cards and supplementary accounts to a primary member. It is used in banking programs where a single member account has multiple cards — for example, a primary cardholder with one or more supplementary cards for family members.CRD is relevant for programs where transactions arrive tagged with a card identifier rather than the primary member’s Relation Reference. Loyalife uses the CRD mapping to resolve the correct member account when evaluating rules and posting points. Without a CRD entry, transactions submitted with an unrecognised card identifier are rejected.
Pre-processing layer
For programs that receive data files from external systems (banks, ERP platforms, payment networks), Loyalife’s pre-processing layer transforms files before ingestion. Pre-processing runs between SFTP upload and Rule Engine evaluation. Any fields a client wants to share — across any file type — are defined as global attributes or custom attributes in Loyalife. The pre-processing layer normalises the incoming file so those fields are correctly structured and can be pushed into Loyalife, where they are stored against the matching member or transaction attribute. This means the client’s source file does not need to match Loyalife’s internal format exactly — the pre-processing configuration handles the mapping. Typical transformations applied during pre-processing include date format normalisation, column merging, header stripping, and field trimming. The specific transformations are configured per program during onboarding based on the client’s source file structure.Multi-program routing (BIN-based)
For programs receiving a single file containing records for multiple loyalty programs (common in banking / card programs), the pre-processing layer can route records to the correct program using a BIN (Bank Identification Number) or equivalent routing key. Each routing key maps to exactly one program. Records with an unrecognised routing key are written to a reject file rather than ingested into any program.File validation
Validation happens at two levels: the file as a whole, and then each row individually.File-level validation
These checks run before any rows are processed. A failure here rejects the entire file:| Validation | Error | Fix |
|---|---|---|
| File is not empty | File should not be empty | Confirm the export from your source system produced records |
| File has at least one data row | File must contain at least one record | Remove header-only files; ensure data rows are present below the header |
| Column headers match the expected template | Invalid file format: Missing required headers / Invalid file format: Found unexpected headers | Re-export using the sample file from the Rule Engine section; do not rename or reorder columns |
| File is CSV or pipe-delimited | Only CSV files are accepted | Convert the file to CSV or the pipe-delimited format configured for your program |
| File name does not exceed 50 characters | File is ignored by the processor | Shorten the filename before uploading |
| File encoding is UTF-8 | File may process incorrectly or fail silently | Save the file as UTF-8 encoded; avoid opening and re-saving in Excel without specifying encoding |
Row-level validation
Each row is validated independently. A failed row is rejected and logged; all other valid rows continue processing:| Validation | Outcome on failure |
|---|---|
| All mandatory fields present | Row rejected |
| Relation Reference exists in Loyalife | Row rejected |
Transaction date is a valid format (YYYY-MM-DD or YYYY-MM-DD HH:MM:SS) | Row rejected |
| Amount is a valid number (not empty, not text) | Row rejected |
| Points value is a valid non-zero number (BNS files) | Row rejected |
| Currency type is a recognised value | Row rejected |
| Duplicate transaction reference | Row skipped (deduplication) |
| Column count matches expected number of columns | Row rejected |
Complete error reference
File-level errors (entire file rejected):| Error message | Cause | Fix |
|---|---|---|
Invalid file format: Missing required headers | One or more expected column headers are absent | Use the sample file template; do not remove or rename columns |
Invalid file format: Found unexpected headers | File has extra columns not in the template | Remove any added columns; match the template exactly |
Invalid file format: Please use the sample file format | General header mismatch | Re-download and re-use the sample file |
File should not be empty | File contains no data | Confirm the source export produced records |
Column count mismatch | A row has more or fewer columns than the header defines | Check for stray commas or missing delimiters; wrap text fields containing commas in double quotes |
Only CSV files are accepted | File is not a supported format | Convert to CSV or pipe-delimited format |
| Error message | Cause | Fix |
|---|---|---|
Member not found | Relation Reference in the row does not match any enrolled member | Verify member IDs against the Members list; re-export from source if out of sync |
Missing mandatory field | A required column is empty for this row | Fill in the missing value or remove the row |
Invalid date format | Transaction date is not in YYYY-MM-DD or YYYY-MM-DD HH:MM:SS format | Correct the date column; confirm pre-processing is applied if source uses a different format |
Date & Time format should be YYYY-MM-DD HH:MM:SS | Combined timestamp column has incorrect format | Ensure date and time columns are merged correctly; check pre-processing configuration |
Amount must be a valid number | Transaction amount is empty, contains text, or is non-numeric | Clean the amount column; remove currency symbols, spaces, or commas used as thousands separators |
Points must be a valid number | Points value in a BNS row is empty or non-numeric | Correct the bonus amount column |
Points cannot be zero | BNS row has a zero bonus amount | Remove zero-value rows or correct the amount |
Invalid currency type | CURRENCY_TYPE value is not MOKAFAA or CASHBACK | Use only the accepted currency type values for your program |
Duplicate transaction reference | A transaction with this reference was already processed | Remove duplicate rows; use unique reference IDs per transaction |
Comma in text field | A CSV field contains an unquoted comma | Wrap fields containing commas in double quotes: "Test transaction, bonus" |
| Error message | Cause | Fix |
|---|---|---|
Error in processing file | A technical error occurred during file processing | Retry the upload; if the error persists, contact your Loyalife administrator |
File processing failed completely due to technical error in the database | Database-level failure during ingestion | Contact your Loyalife administrator — this requires investigation on the backend |
The log file is no longer available for download | The error log has been automatically deleted per the program’s report retention settings | Download error logs promptly after upload; check program retention period settings |
Rule evaluation on batch files
After validation, each accepted row is evaluated against all active rule groups, following the same logic as real-time API transactions:- Member’s segment membership is checked against each rule group’s linked segment
- IF conditions are evaluated against the transaction’s attributes
- Matching rules apply their THEN reward
- Points are posted to the member’s account
- Tier re-evaluation is triggered for the member
Error file delivery (SFTP return)
After processing, Loyalife can automatically deliver the error file (rows that failed validation) back to the client’s SFTP server. This enables fully automated pipelines where the client system receives rejected rows without accessing the Loyalife UI. This feature is configured per program and supports selective file types (e.g., only CPD and TXN error files, not BNS). Error files are placed in the client’s designated inbound SFTP path. The file naming convention mirrors the input file with a suffix indicating it is a rejection report.Error file delivery to client SFTP is enabled by the Loyalife operations team during program setup. It is not available as a self-service toggle in the admin UI.
Monitoring uploads
Go to Reports & Analytics → Data Exports → Logs to see:| Column | Description |
|---|---|
| Upload timestamp | When the file was received |
| File name | The original filename |
| Total rows | Total records in the file |
| Processed | Successfully evaluated records |
| Rejected | Rows that failed validation |
| Status | Completed, Processing, Failed |
Troubleshooting
File uploaded but no points were awarded.- Check the Logs report for the file’s processing status.
- Review the rejection count — if all rows were rejected, look at the error messages.
- Verify Relation References in the file match enrolled members in Loyalife.
- Confirm active rule groups exist for the members and transaction types in the file.
- Confirm you are connected to the approved VPN.
- Verify credentials are correct and have not expired.
- Contact your Loyalife administrator to check SFTP server status.
- Verify the file was uploaded to the correct directory for its type (
upload/TXN,upload/CPD,upload/BNS,upload/CRD). - Check file encoding — Loyalife expects UTF-8 encoded files.
- Ensure the first row is the header row and that column names match the configured template exactly.
- Loyalife can send email notifications when a CPD, TXN, or BNS file finishes processing. The Super Admin is always notified. Additional email addresses can be added under Program Settings → Notifications. Contact your Loyalife administrator to configure this.