Bulk Upload Consents via SFTP

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

Overview

The SFTP Bulk Consent Upload feature allows you to upload multiple consent documents at scale without using the API for each individual file. This is ideal for:

• High-volume uploads: Process hundreds or thousands of consent documents efficiently
• Batch operations: Upload multiple files simultaneously
• Simplified integration: Use standard SFTP clients instead of API integration
• Automated workflows: Set up automated file transfers from your systems

After your consent documents are uploaded and confirmed, you can proceed to make Payment Requests to debit your customer's accounts.

Flow

The bulk upload process works as follows:

1. Upload Files: You upload consent documents to your dedicated SFTP directory.
2. Automatic Processing: Our system monitors your directory and processes new files every 15 minutes. The processing steps include:
   • Validation: Each file is validated for naming, size, and content.
   • Consent Creation: Files are automatically linked to existing payment methods and consents.
3. Feedback: You receive confirmation or error messages in your outbound directory.

Prerequisites

Before uploading consent files via SFTP, you must:

1. Create Customer Records and Register Payment Methods

   You must have the customers and their associated Payment Methods registered in the Belvo platform before performing the bulk SFTP consent operation. We recommend using our Bulk Import Direct Debit Payments feature to automatically create customers and payment methods in bulk. In the initial upload, you can omit the Referencia Única cliente and Importe a cobrar fields, as these are not required for Customer and Payment Method creation.

2. SFTP Credentials

   Obtain your SFTP access credentials from the Belvo support team. Please note, we only allow one SFTP account per merchant.

SFTP Directory Structure

Your SFTP account has two dedicated directories:

├── inbound/
│   └── bulk-consents/     ← Upload consent documents here
└── outbound/
    └── bulk-consents/     ← Feedback messages appear here

• Inbound Directory: Upload your consent documents to the inbound/bulk-consents/ directory, according to the file naming conventions and specifications outlined below.
• Outbound Directory: Processed files and feedback messages will be available in the outbound/bulk-consents/ directory.

File Specifications

For your consent document uploads to be accepted, they must adhere to the following specifications:

File Naming Convention

All uploaded files must follow this exact naming pattern:

Naming Pattern:
consent_<idDocumentType>_<idDocumentNumber>_<accountNumber>_<documentType>.<extension>

Valid File Names:
✅ consent_mx_rfc_ABCD123456_012345678901234567_id_front.pdf
✅ consent_mx_curp_XYZ789012_987654321098765432_id_back.png
✅ consent_mx_rfc_DOC123456_111122223333444455_selfie.jpg
✅ consent_mx_curp_TEST789_666677778888999900_contract.pdf

Invalid File Names:
❌ invoice_ABCD123456_012345678901234567_id_front.pdf -> (Wrong prefix - must be "consent_")
❌ consent_ABCD_id_front.pdf -> (Missing account number)
❌ consent_ABCD_1234_document.pdf -> (Invalid document type - must be one of: id_front, id_back, selfie, contract)
❌ consent_ABCD_1234_id_front -> (Missing file extension)
❌ consent_mx_rfc_ABCD123456_12AB_id_front.pdf -> (Account number must be numeric only)

Consent Document Types

For each customer, you must upload four consent document files:

File Size Limits

Each uploaded file must adhere to the following size constraints:

• Minimum size: 100 bytes
• Maximum size: 20 MB per file

Supported File Formats

• PDF: .pdf (recommended for contracts)
• PNG: .png (recommended for IDs and selfies)
• JPEG: .jpg (acceptable for all document types)

Image Quality Recommendations

• Resolution: Minimum 300 DPI for ID documents
• Clarity: Ensure text is readable and photos are clear
• Orientation: Images should be properly oriented (not rotated)
• Color: Color images preferred over black and white

Upload Process

1. Connect to SFTP using your preferred software (for example, Cyberduck). Use the credentials provided by the Belvo support team.
2. Navigate to the inbound/bulk-consents/ directory.
3. Upload your consent document files to this directory.
4. Wait for the files to be processed. Our system checks your inbound directory every 15 minutes for new files. Each batch of files takes approximately 30 minutes to process, depending on volume.
5. Check the outbound/bulk-consents/ directory for feedback files indicating success or errors for each uploaded file.

After Upload

After uploading your consent documents, you need to check the feedback files in the outbound directory (outbound/bulk-consents/) to confirm whether the uploads were successful or if there were any errors. You will need to open each feedback file to see the processing results.

The file names in the outbound directory will match the uploaded files, for example:

consent_mx_rfc_ABCD123456_012345678901234567_id_front_pdf.txt

Successful Uploads

For successful file uploads (the file was accepted and linked to a consent ID), the feedback file will contain the following information:

File 120890e5-21fd-47d1-bba1-3f2a6a1fe6d2/inbound/bulk-consents/consent_mx_rfc_ABCD123456_012345678901234567_id_front.pdf successfully stored for consent 2455bbd7-1b12-4195-8de0-121c10268886.

Unsuccessful Uploads

For unsuccessful uploads, the feedback file will detail the reasons for rejection. For example:

File consent_mx_rfc_ABCD123456_012345678901234567_id_front.pdf rejected because:
* originalFilename must start with "consent_"
* accountNumber must be numeric

In this case, you will need to correct the issues mentioned and re-upload the file.

Common Errors

File Naming Errors

originalFilename must start with "consent_"

• Cause: File name doesn't begin with "consent_"
• Solution: Rename file to start with "consent_" prefix

accountNumber must be numeric

• Cause: Account number contains letters or special characters
• Solution: Ensure account number is digits only (e.g., CLABE number)

consentDocumentType must be one of the following values: id_front, id_back, selfie, contract

• Cause: Invalid document type in filename
• Solution: Use only: id_front, id_back, selfie, or contract

extension must be one of the following values: pdf, png, jpg

• Cause: Unsupported file format
• Solution: Convert file to PDF, PNG, or JPG format

File Size Errors

File size must be at most 20000000 bytes (20 MB)

• Cause: File exceeds maximum size limit
• Solution: Compress or resize the file to under 20 MB

File size must be at least 100 bytes

• Cause: File is empty or corrupted
• Solution: Ensure file contains actual content and is not corrupted

Payment Method Errors

payment method not found for the given account and customer

• Cause: No payment method exists matching the document number and account number
• Solution:

  1. Check idDocumentNumber matches your customer record exactly.

     You can use the List all customers API request, using document number or name in the search query parameter.

  2. Verify the payment method was created (using our API). Create payment method if it doesn't exist.

     You can use the List all payment methods, using the customer_id query parameter to view all payment methods created for the customer. If a payment method doesn't exist, use the Create a payment method API request to create a new payment method for the customer.

  3. Confirm accountNumber matches the payment method exactly.

File Processing Errors

File not appearing in outbound directory after 30+ minutes

Possible causes and solutions:

If the files do not appear after 60 minutes, please contact Belvo support.

Best Practices

Below are some best practices to ensure a smooth bulk consent upload process via SFTP.

Before Uploading

1. Validate Data First

   • Ensure customers exist in the system.
   • Verify payment methods are registered.
   • Double-check document and account numbers match records.

   Check out the Payment Method Errors section for tips how to do this using our API.

2. Test with Small Batch Before uploading large volumes of files:

   • Upload one or two files first to verify setup is correct.
   • Check the feedback messages.
   • Proceed with larger batches after successful test.

3. Organize Files Locally

   • Keep a local copy of all uploaded files (with a consistent naming convention).
   • Track which files belong to which consents.

During Upload

1. Upload Complete Sets
   • Upload all four required documents for each consent when possible as this triggers consent processing.
2. Avoid Duplicate Uploads
   • Don't upload the same file multiple times. Wait for feedback before re-uploading
3. Check File Integrity
   • Verify files aren't corrupted before upload and open correctly on your local system.

After Upload

1. Monitor Feedback Directory
   • Check outbound directory after 30 minutes
   • Download and review all feedback files
   • Take action on errors promptly
2. Track Consent Status
   • Monitor your received webhook events to check consent statuses (or poll our API using the Get a Consent's details API request.)
   • Monitor progression through: awaiting_information → submitted → confirmed/rejected
3. Archive Processed Files
   • Keep records of successfully uploaded files
   • Document feedback messages
   • Maintain an audit trail for compliance and troubleshooting

Consent Lifecycle

Once all consent documents are successfully uploaded via SFTP, they progress through the following lifecycle stages:

To check the details of a consent, use the Get a Consent's details API request.

Next Steps

Once a consent is confirmed:

• You do not need to take any further actions regarding the consent itself. The consent is valid until revoked by customer or expired per agreement
• The associated Payment Method can be used for payments.