# Upload Batch Imports via SFTP ## Overview The SFTP Batch Import feature allows you to upload CSV files containing payment data to automate the creation of customers, payment methods, and payment requests at scale. This is the same batch import functionality available through the Merchant Portal and API, but with the added convenience of file-based automation via SFTP. This feature is ideal for: - **Automated workflows**: Set up scheduled file transfers from your systems - **High-volume processing**: Process thousands of payment requests efficiently - **System integration**: Connect your existing batch processes without API integration - **Operational simplicity**: Use standard SFTP clients instead of custom API code Feature Enablement SFTP Batch Imports must be enabled for your merchant account. Contact Belvo support to request access to this feature. Get User Consent to Debit Accounts Before making any payment requests, you must: 1. Obtain explicit consent from your users, authorizing you to debit funds from their accounts. 2. Maintain documented evidence of this consent. For more information, see our Bulk Upload Consents via SFTP guide. ## How It Works The SFTP batch import process mirrors the Bulk Import Direct Debit Payments feature available in the Merchant Portal, with file-based automation: 1. **Upload CSV**: You upload a CSV file (using the same format as portal uploads) to your SFTP inbound directory. 2. **Automatic Pickup**: Belvo monitors your inbound directory and picks up new files every 15 minutes, Monday through Friday. 3. **Processing**: The system validates and processes your file, creating customers, registering payment methods, and submitting payment requests. 4. **Feedback**: A `.txt` feedback file is generated in your outbound directory with the processing results. Webhooks and API Access SFTP batch import processing triggers the same webhooks and updates the same API resources as portal or API-based batch imports. The SFTP feedback file is an additional notification mechanism, not a replacement for webhooks. ## Prerequisites Before uploading batch import files via SFTP, ensure you have: 1. **SFTP Batch Imports Enabled** Contact Belvo support to enable SFTP batch imports for your merchant account. 2. **SFTP Credentials** Obtain your SFTP access credentials from the Belvo support team. Please note, we only allow one SFTP account per merchant. 3. **Consent Documentation** Ensure you have obtained and documented consent for all customers included in your batch import. You can upload consents using the SFTP Bulk Upload Consents feature or the Consent API. 4. **CSV File Prepared** Prepare your CSV file following the same format used for portal uploads. For field specifications, see the Bulk import file templates documentation. ## SFTP Directory Structure Your SFTP account has two dedicated directories for batch imports: ``` ├── {merchantId}/ │ ├── inbound/ │ │ └── batch_imports/ ← Upload CSV files here │ └── outbound/ │ └── batch_imports/ ← Feedback files appear here ``` - **Inbound Directory** (`{merchantId}/inbound/batch_imports/`): Upload your CSV files to this directory. Files must follow the same CSV format used in the Merchant Portal. - **Outbound Directory** (`{merchantId}/outbound/batch_imports/`): Belvo writes feedback `.txt` files here. You do **not** create this folder yourself—Belvo provisions it. You **read** or download from outbound when files are available. Create batch imports folder if needed If `batch_imports/` does not exist under `{merchantId}/inbound/`, **create that folder manually** in your SFTP client before you upload. ## File Specifications ### CSV Format Batch import CSV files must follow the same format as portal uploads. For the complete field specification, see the Bulk import file templates documentation. Bulk Create Payment Methods Only You can also use this feature to bulk create customers and payment methods without making payment requests. To do this, omit the **Referencia Única cliente** and **Importe a cobrar** fields in your CSV. ### File Naming You can use any valid filename for your CSV files. We recommend using descriptive names that include a date or batch identifier for your own tracking purposes. ``` Valid File Names: ✅ payments_2026-04-08.csv ✅ batch_001.csv ✅ monthly_debits_april.csv ``` Ignored objects Empty files, zero-byte objects, and directory placeholder entries under `batch_imports` are ignored and are not processed. ## Upload Process 1. Connect to SFTP using your preferred software (for example, Cyberduck, FileZilla, or command-line tools). Use the credentials provided by the Belvo support team. 2. Navigate to your `{merchantId}/inbound/batch_imports/` directory. 3. Upload your CSV file to this directory. 4. Wait for the file to be processed. Belvo checks your inbound directory every 15 minutes, Monday through Friday. 5. Check the `{merchantId}/outbound/batch_imports/` directory for a `.txt` feedback file with your processing results. Processing Schedule Files are picked up every 15 minutes, Monday through Friday. Files uploaded outside of business hours or on weekends will be processed on the next business day. File Removal After a file is picked up for processing, Belvo attempts to remove it from the inbound directory to prevent duplicate processing. If removal succeeds, the same file will not be picked up again. If removal fails (rare), the object may still appear in listings on a later run and could be processed again—contact Belvo support or remove or rename the file manually if you see stale files after you already received feedback. ## Feedback Files After processing, a `.txt` feedback file is written under `{merchantId}/outbound/batch_imports/`. ### Feedback file naming The outbound name is derived from your CSV filename: the base name and extension are kept, **dots (`.`) in the name or extension are replaced with underscores**, and a **Unix timestamp in milliseconds** is appended. The extension is always `.txt`. Examples: - `payments_2026-04-08.csv` → `payments_2026-04-08_csv_1775590260741.txt` - `batch.import.csv` → `batch_import_csv_.txt` Use the timestamp (and your upload log) to match feedback files to uploads when several runs occur close together. ### When Feedback is Generated - **Validation/preparation failures**: Failure feedback is sent on that path as soon as the batch import cannot proceed (including when validation fails before a batch record exists). - **Successful path**: After validation passes and the batch is **sent for processing**, success or terminal failure feedback is written only when the batch reaches a **terminal** state (`processed` or `failed`). The system rechecks approximately **every minute**, so there may be a delay between the file disappearing from inbound and the `.txt` appearing in outbound. ### Format Overview - The first line always references the **original CSV filename** and either **processed successfully** or **could not be processed**. - When a batch import record exists, the first line includes `(batchImportId: )`. If processing fails before a batch ID is created, the first line has **no** batch import ID. - **Skipped rows** (success only) are listed as **CSV-like lines** (same shape as the bulk import row data), not as “Row N:” summaries. - **Errors** use the same structure as row validation errors in the Merchant Portal: numbered blocks, bullet messages, and an optional `Row:` section with field keys and **masked** sensitive values. ### Success Feedback When the batch ends in `processed` status, the body looks like this: ``` Example — clean success File payments_january.csv processed successfully (batchImportId: 3f8e7d6c-5b4a-3210-fedc-ba9876543210). 0 row(s) were skipped. ``` With skipped rows: ``` Example — success with skipped rows File payments_january.csv processed successfully (batchImportId: 3f8e7d6c-5b4a-3210-fedc-ba9876543210). 2 row(s) were skipped. Skipped rows (2): RFC,ABCD123456ABC,john@example.com,John,Doe,+521234567890,****1234,savings,500,REF001,,mxn RFC,XYZW987654XYZ,jane@example.com,Jane,Smith,+529876543210,****5678,savings,250,REF002,,mxn ``` Masked values Account and other sensitive fields appear **masked** in feedback (for example `****1234`), consistent with the bulk import experience in the Merchant Portal. ### Success with tolerated row errors This shape appears only when the batch **still completes as `processed`** but some rows had tolerable validation issues. The section title in the file is **`Rows with errors (tolerated)`**: ``` Example — processed with tolerated row errors File payments_january.csv processed successfully (batchImportId: 3f8e7d6c-5b4a-3210-fedc-ba9876543210). 1 row(s) were skipped. Skipped rows (1): RFC,ABCD123456ABC,john@example.com,John,Doe,+521234567890,****1234,savings,500,REF001,,mxn Rows with errors (tolerated) (1): -- Error 1: * accountNumber length must be 18 characters Row: firstname: John lastname: Doe accountNumber: ****1234 amount: 500 ``` If validation rules cause the **whole batch** to fail (for example tolerance off or too many errors), you receive **failure** feedback instead—not this success template. ### Failure Feedback When preparation or terminal processing fails with structured errors: ``` Example — failure with validation errors File payments_january.csv could not be processed (batchImportId: 3f8e7d6c-5b4a-3210-fedc-ba9876543210). Errors (2): -- Error 1: * email must be an email Row: email: not-a-valid-email amount: 50 currency: mxn firstname: Bad lastname: Email -- Error 2: * documentType must be one of the following values: mx_rfc, mx_curp Row: email: jane@example.com documentType: mx_xyz documentNumber: BADD141414NNN ``` When there is no batch import ID yet: ``` Example — failure before batch import ID exists File payments_january.csv could not be processed. Errors (1): -- Error 1: * email must be an email Row: email: invalid ... ``` ### Unexpected error feedback When there is no structured error list (for example an unexpected processing error), the file contains only the header and a fixed second line: ``` Example — unexpected error File payments_january.csv could not be processed (batchImportId: 3f8e7d6c-5b4a-3210-fedc-ba9876543210). Due to an unexpected error. ``` If no batch was created, the first line is `File .csv could not be processed.` without `(batchImportId: ...)`, followed by a blank line and `Due to an unexpected error.` ## Batch Import Lifecycle Batch imports uploaded via SFTP follow the same lifecycle as portal uploads: | Status | Description | | --- | --- | | `validating` | The file is being validated for format and content errors. | | `failed` | The file has critical errors and cannot be processed. Check the feedback file for details. | | `ready_to_send` | Validation passed. For SFTP uploads, processing continues automatically. | | `processing` | Customers, payment methods, and payment requests are being created. | | `processed` | Processing complete. Check the feedback file for results including any skipped rows. | Automatic Processing Unlike portal uploads where you must manually click "Send" after validation, SFTP uploads are automatically sent for processing once validation passes. ## Troubleshooting ### File not appearing in outbound directory | Cause | Solution | | --- | --- | | File is still being processed | Wait at least 30 minutes after upload. Processing can take longer for large files. | | File uploaded outside processing hours | Files are picked up Monday through Friday only. Wait until the next business day. | | Batch is still processing payment requests | For batches that pass validation, feedback is generated only after the batch reaches `processed` or `failed` status. | | File was uploaded to wrong directory | Verify you uploaded to `{merchantId}/inbound/batch_imports/` (not `bulk-consents`). | ### File remains in inbound directory In rare cases, a file may remain in the inbound directory after processing because deletion failed. That object might be picked up again on a later run. If you already received feedback for that upload, contact Belvo support or remove or rename the file manually. If you are unsure, check batch status via the API or Merchant Portal before re-uploading. ### Common validation errors For common CSV validation errors and their solutions, refer to the Troubleshooting and FAQs section in the Bulk Import documentation. ## Best Practices ### Before Uploading 1. **Validate your CSV locally** - Ensure all required fields are present - Verify CLABE numbers are 18 digits - Check that email addresses are valid - Confirm ID types are `mx_curp` or `mx_rfc` 2. **Test with small batches first** - Upload a file with a few rows to verify your format is correct - Check the feedback file before uploading large batches 3. **Ensure consents are in place** - All customers should have confirmed consents before payment requests are created - Use the SFTP Bulk Upload Consents feature to upload consent documents ### During Upload 1. **Use descriptive file names** - Include dates or batch identifiers for easy tracking - Keep a local record of uploaded files 2. **Avoid duplicate uploads** - Wait for feedback before uploading the same data again - Use unique references for each payment request ### After Upload 1. **Monitor feedback files** - Check your outbound directory regularly - Review skipped rows and errors promptly 2. **Track via webhooks** - Set up webhook listeners for batch import events - Use the API to check batch status for detailed information 3. **Maintain audit trails** - Archive feedback files for compliance - Document any errors and resolutions ## Next Steps After setting up SFTP batch imports: - Review the CSV field specifications to ensure your files are correctly formatted. - Set up webhook listeners to receive real-time notifications about your batch imports. - Use the Payment Exports feature to reconcile processed payments.