Skip to content
Last updated

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_<timestamp>.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: <uuid>). 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 <name>.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:

StatusDescription
validatingThe file is being validated for format and content errors.
failedThe file has critical errors and cannot be processed. Check the feedback file for details.
ready_to_sendValidation passed. For SFTP uploads, processing continues automatically.
processingCustomers, payment methods, and payment requests are being created.
processedProcessing 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

CauseSolution
File is still being processedWait at least 30 minutes after upload. Processing can take longer for large files.
File uploaded outside processing hoursFiles are picked up Monday through Friday only. Wait until the next business day.
Batch is still processing payment requestsFor batches that pass validation, feedback is generated only after the batch reaches processed or failed status.
File was uploaded to wrong directoryVerify 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:

Previous page
Next page
Copyright © 2020-2025 Belvo. All rights reserved