/v2/files/uploadUpload File
Upload documents and receive a File ID for use in other APIs wherever file-type parameters are required.
Common flows: • Outbound bank payments (invoices, supporting documents) • Virtual account creation (KYC and identity documents)
How it works: • Upload a file using this endpoint • The system returns a File ID • Pass that File ID in other API requests where a file field is required
Query parameters (see table below): • customField — defines where the file will be used; must match the target API field • fileName — file name including extension (e.g. .pdf, .png)
Usage mapping: • Payments / SupportingDocument → customField Payment_Invoice • Add Virtual Account (business beneficiary) / Document_File → customField Document_File • Add Virtual Account (individual beneficiary) / Front_Document → customField Front_Document • Add Virtual Account (individual beneficiary) / Back_Document → customField Back_Document
Key notes: • File ID is required for any file-type field • customField must match the field where the file will be used • fileName must reflect the actual file type uploaded • Uploaded files can be reused across flows
File constraints: • Maximum file size: 5 MB • Maximum file name length: 100 characters
Examples: • Upload an invoice, then use the File ID in SupportingDocument when creating a payment • Upload ID proof, then use the File ID in Front_Document or Back_Document during beneficiary creation
Summary: Upload File → get File ID → use in Payments, Beneficiary, or Virtual Account APIs.
Query parameters
| Field | Type | Required | Possible values | Description |
|---|---|---|---|---|
customField | string | Required | Payment_Invoice | Document_File | Front_Document | Back_Document | Target API field that will reference this file (e.g. Payment_Invoice, Document_File, Front_Document, Back_Document). Must match usage in the downstream request. |
fileName | string | Required | {fileName.extension} | File name including extension (e.g. invoice.pdf, id-front.png). Max 100 characters. |
Headers
| Field | Type | Required | Possible values | Description |
|---|---|---|---|---|
Authorization | string | Required | Bearer {SessionToken} | Session token from Get Session Token, sent as `Authorization: Bearer {SessionToken}`. Replace with the value from the `x-refresh-token` response header when present (typically within 2 minutes of expiry). Secured calls must use the same IP as the auth request. |
Request body
| Field | Type | Required | Possible values | Description |
|---|---|---|---|---|
file | file | Required | File | Binary file content (PDF, PNG, JPG, or JPEG). Send as the raw request body with the file Content-Type. |
Response
| Field | Type | Possible values | Description |
|---|---|---|---|
ResponseCode | integer | 200 | 201 | 204 | 400 | 401 | 403 | 404 | 410 | 422 | 500 | 301 | 503 | 422 | API result code in the response envelope. Indicates success or the error category (e.g. 200 success, 400 bad request, 401 unauthorized). |
ResponseMessage | string | Success | Created | NoContent | BadRequest | Unauthorized | Forbidden | NotFound | Gone | UnprocessableContent | ServerError | ResourceMoved | ServiceUnAvailable | UnProcessableEntity | Human-readable label paired with ResponseCode (e.g. Success, BadRequest, Unauthorized). Use with ResponseCode to interpret the outcome. |
ResponseData | object | Please refer to below example for response body | Uploaded file ID. Pass this value in SupportingDocument, Document_File, and other file fields. |
Example response
{
"ResponseCode": 200,
"ResponseMessage": "Success",
"ResponseData": {
"ID": "6236251066802286564"
}
}Requires `Authorization: Bearer {SessionToken}` from Get Session Token. Refresh via `x-refresh-token` when supplied; use the same client IP as authentication.