File Upload

Overview

The File Upload API allows you to upload documents and supporting files required for verification purposes. Uploaded files can be referenced when creating recipients or merchants.

Resource Access

• HTTP Method: POST
• Endpoint: /banking/iban/api/file/v2/upload
• Authentication: Bearer token required
• Content Type: multipart/form-data

Request Headers

Header	Value	Required	Description
Authorization	Bearer {access_token}	Yes	Bearer token for authentication
Content-Type	multipart/form-data	Yes	Form data content type

Request Body

The request should be sent as multipart/form-data with the following field:

Field	Type	Required	Description
file	file	Yes	The file to upload

Supported File Types

• PDF documents (.pdf)
• Image files (.jpg, .jpeg, .png)
• Document files (.doc, .docx)

File Size Limits

• Maximum file size: 10 MB
• Recommended file size: Under 5 MB for optimal processing

Response

Success Response (200 OK)

{
  "file_id": "8f7d6e5c-4b3a-2f1d-9e8c-7b6a5d4c3f2e",
  "filename": "verification_document.pdf",
  "file_size": 245760,
  "content_type": "application/pdf",
  "upload_date": "2026-01-13T10:00:00.000Z",
  "status": "uploaded"
}

Response Fields

Field	Type	Description
file_id	string (UUID)	Unique identifier for the uploaded file
filename	string	Original filename
file_size	integer	File size in bytes
content_type	string	MIME type of the file
upload_date	string (date-time)	Upload timestamp
status	string	Upload status

File Status Values

• uploaded: File successfully uploaded
• processing: File is being processed
• verified: File has been verified
• rejected: File rejected due to quality or content issues

Error Responses

• 400 Bad Request: Invalid file type or missing file
• 401 Unauthorized: Invalid or missing authentication token
• 413 Payload Too Large: File size exceeds maximum limit
• 415 Unsupported Media Type: File type not supported
• 500 Internal Server Error: Server error occurred

Code Examples

cURL

curl -X POST \
  'https://gateway.ahrvo.network/banking/iban/api/file/v2/upload' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -F 'file=@/path/to/document.pdf'

Python

import requests

url = "https://gateway.ahrvo.network/banking/iban/api/file/v2/upload"
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN"
}
files = {
    'file': open('/path/to/document.pdf', 'rb')
}

response = requests.post(url, headers=headers, files=files)
print(response.json())

JavaScript (Node.js)

const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');

const url = 'https://gateway.ahrvo.network/banking/iban/api/file/v2/upload';
const headers = {
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
};

const formData = new FormData();
formData.append('file', fs.createReadStream('/path/to/document.pdf'));

axios.post(url, formData, { 
  headers: {
    ...headers,
    ...formData.getHeaders()
  }
})
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.error(error.response.data);
  });

Python with Async

import aiohttp
import asyncio

async def upload_file():
    url = "https://gateway.ahrvo.network/banking/iban/api/file/v2/upload"
    headers = {
        "Authorization": "Bearer YOUR_ACCESS_TOKEN"
    }
    
    with open('/path/to/document.pdf', 'rb') as f:
        data = aiohttp.FormData()
        data.add_field('file', f, filename='document.pdf')
        
        async with aiohttp.ClientSession() as session:
            async with session.post(url, headers=headers, data=data) as response:
                result = await response.json()
                print(result)

asyncio.run(upload_file())

Usage Notes

• Store the returned file_id for use when creating recipients or merchants
• Ensure files are clear and legible for verification purposes
• Supported file types may vary by region and verification requirements
• Files are automatically scanned for malware and quality
• Uploaded files are stored securely and encrypted
• Files may be automatically deleted after a retention period
• Check file status before using in recipient/merchant creation

Document Types

Common document types that may be required:

• Identity Documents: Passport, national ID, driver's license
• Proof of Address: Utility bills, bank statements
• Business Documents: Business registration, tax certificates
• Banking Documents: Bank statements, voided checks

Best Practices

1. Image Quality: Ensure documents are clear and all text is readable
2. File Format: Use PDF for multi-page documents
3. Compression: Compress large files while maintaining readability
4. Naming: Use descriptive filenames for easier tracking
5. Security: Never include sensitive data in filenames
6. Verification: Verify file upload success before proceeding

Interactive API Explorer