Upload Onboarding Files
Upload business documents for merchant onboarding verification
Overview
Uploads business documents required for merchant onboarding and KYC (Know Your Customer) verification. This endpoint accepts multiple document types including valid IDs, business permits, certificates, and supporting documents.Authentication
This endpoint requires JWT Bearer Token authentication.Authorization Rules
Path Parameters
^\d+$Example: "12345"Request Body
multipart/form-data encoding. Each field should contain the actual binary file content, not strings, URLs, or base64-encoded data.multipart/form-data. When uploading files, ensure you’re using proper file upload mechanisms in your programming language (e.g., fs.createReadStream() in Node.js, open() in Python, CURLFile in PHP) rather than sending text or encoded strings.
File Requirements
Allowed Formats
File Size Limit
File Name Length
Validation Levels
Required Documents by Business Type
STARTER
STARTER
- Valid ID(s) of Signatory
- Photo of store with store name
- Barangay Business Permit
- Incorporator’s Government Issued ID
- Signatory’s Government Issued ID
- Authorized Representative Government Issued ID
SOLE_PROPRIETOR
SOLE_PROPRIETOR
- Valid ID(s) of Signatory
- Incorporator’s Government Issued ID
- Signatory’s Government Issued ID
- Authorized Representative Government Issued ID
- Either of the two:
- Business/Mayor’s Permit OR
- BIR Certificate of Registration (2303)
PARTNERSHIP
PARTNERSHIP
- Valid ID(s) of Signatory
- Incorporator’s Government Issued ID
- Signatory’s Government Issued ID
- Authorized Representative Government Issued ID
- List of Goods/Services sold with Pricing
- Refund and Refund Policy
- Fulfillment Policy
- Privacy Policy
- At least one of the following:
- Business/Mayor’s Permit OR
- BIR Certificate of Registration (2303) OR
- SEC Registration Certificate
- AOI and By-Laws
- Secretary’s Certificate
CORPORATION
CORPORATION
- Valid ID(s) of Signatory
- Incorporator’s Government Issued ID
- Signatory’s Government Issued ID
- Authorized Representative Government Issued ID
- List of Goods/Services sold with Pricing
- Refund and Refund Policy
- Fulfillment Policy
- Privacy Policy
- At least one of the following:
- Mayor’s or Business Permit OR
- BIR Certificate 2303 OR
- SEC Certificate
- Either of the two:
- Article of Partnership/Incorporation (AOI) and By-Laws OR
- General Information Sheet (GIS)
- Secretary’s Certificate (mandatory for Corporation)
Document Fields
Each document type supports front, back, and signature images where applicable. All fields accept arrays to support multiple file uploads.Valid IDs
Mayor’s Permit / Business Permit
BIR Certificate 2303
SEC Certificate
General Information Sheet (GIS)
Articles of Incorporation and By-Laws
Secretary’s Certificate
Barangay Business Permit
Store Photo
Response
Success Response
Status Code:200 OK
Error Responses
400 Bad Request - Invalid Merchant ID
400 Bad Request - Invalid Merchant ID
400400 Bad Request - Merchant ID Mismatch
400 Bad Request - Merchant ID Mismatch
400400 Bad Request - No Files Received
400 Bad Request - No Files Received
400400 Bad Request - Invalid File Content Type
400 Bad Request - Invalid File Content Type
400400 Bad Request - Invalid File MIME Type
400 Bad Request - Invalid File MIME Type
400400 Bad Request - Invalid File Extension
400 Bad Request - Invalid File Extension
400400 Bad Request - File Name Too Long
400 Bad Request - File Name Too Long
400400 Bad Request - File Size Too Large
400 Bad Request - File Size Too Large
400400 Bad Request - Failed to Save
400 Bad Request - Failed to Save
400429 Too Many Requests
429 Too Many Requests
429Security Features
This endpoint implements OWASP File Upload Cheat Sheet best practices:Extension Validation
MIME Type Validation
Magic Bytes Validation
File Size Limits
File Name Sanitization
Secure Storage
Best Practices
Upload Files Before Submitting Onboarding
Upload Files Before Submitting Onboarding
Validate Files Client-Side First
Validate Files Client-Side First
Handle Rate Limiting Gracefully
Handle Rate Limiting Gracefully
Organize Files by Document Type
Organize Files by Document Type
Compress Images Before Upload
Compress Images Before Upload
Show Upload Progress
Show Upload Progress
Use Cases
Initial Document Upload
Document Updates
Additional Documents
Document Corrections
Troubleshooting
Sending Strings Instead of Binary Files
Sending Strings Instead of Binary Files
No files received or Invalid file content typeIssue: Sending file paths, URLs, or base64-encoded strings instead of actual binary file dataIncorrect Examples:Magic Bytes Validation Failure
Magic Bytes Validation Failure
Invalid file content typeIssue: File extension doesn’t match actual file contentCommon Causes:- Renamed file with wrong extension (e.g., .txt renamed to .jpg)
- Corrupted file
- File created by unsupported software
- Use legitimate image editing or PDF software
- Don’t just rename file extensions
- Verify file opens correctly before uploading
- Try converting file to correct format using standard tools
File Too Large Even After Compression
File Too Large Even After Compression
File size exceeds 25MB limitSolutions:- For PDFs: Split multi-page documents across front/back/signature fields
- For images: Reduce resolution (1920px width is usually sufficient)
- For images: Convert to JPEG with 80-85% quality
- For images: Use online compression tools like TinyPNG or Squoosh
- Consider splitting document into multiple logical files
Rate Limit Issues During Bulk Upload
Rate Limit Issues During Bulk Upload
429 Too Many RequestsIssue: Trying to upload files for multiple merchants quicklySolutions:- Implement rate limiting in your application (max 5 requests per 60s)
- Add delays between merchant file uploads
- Queue uploads and process with appropriate spacing
- Use exponential backoff for retries
Multipart Form Data Encoding Issues
Multipart Form Data Encoding Issues
File Name Sanitization Concerns
File Name Sanitization Concerns
- Special characters removed
- Path traversal sequences removed (../, ..)
- Length truncated to 255 characters
- Use simple, descriptive file names
- Avoid special characters
- Use the returned
idfield to reference files, notname - Store your own mapping of file IDs to original names if needed
Document Checklist
Use this checklist to ensure you have all required documents before uploading:- STARTER
- SOLE_PROPRIETOR
- PARTNERSHIP
- CORPORATION
- Valid ID(s) of Signatory
- Photo of store with store name
- Barangay Business Permit
- Incorporator’s Government Issued ID
- Signatory’s Government Issued ID
- Authorized Representative Government Issued ID
Next Steps
Onboard Merchant
Retrieve Onboarding Status
Update Onboarding Data
Error Handling
Authorizations
JWT Bearer token authentication
Path Parameters
The merchant's account ID (numeric string)
^\d+$Body
Valid government-issued IDs of authorized signatories (front side)
Back side of valid IDs
Signature specimen from valid IDs
Mayor's Permit or Business Permit (front)
Back side of Mayor's/Business Permit
Signature page of Mayor's/Business Permit
BIR Certificate of Registration (Form 2303) - front
Back side of BIR Certificate 2303
Signature page of BIR Certificate 2303
SEC Certificate - front
Back side of SEC Certificate
Signature page of SEC Certificate
General Information Sheet - front
Back side of GIS
Signature page of GIS
Articles of Incorporation and By-Laws - front
Back side of AOI and By-Laws
Signature page of AOI and By-Laws
Secretary's Certificate - front
Back side of Secretary's Certificate
Signature page of Secretary's Certificate
Barangay Business Permit - front
Back side of Barangay Business Permit
Signature page of Barangay Business Permit
Photo of the store/business establishment (must show visible store name)
Response
Files uploaded successfully
List of successfully uploaded files