Request File Upload URL

Purpose:
General-purpose file upload entry. File bytes never pass through the Open API: you request a short-lived pre-signed URL, PUT the file straight to object storage, and then reference the stored file by fileId in whichever business API accepts a file reference.

How to use:

POST /v1/files/upload-url describing the file you are about to upload. You get back a fileId and a one-shot uploadUrl.

Send the raw file body to the returned uploadUrl with HTTP PUT. The signature is already in the query string — do not send your Open API credentials or any Authorization header.

Finish the PUT before expiresAt (10 minutes from issue). An expired URL cannot be renewed — request a new one and use the new fileId.

Pass fileId to the business API that consumes the file. Example scenario: a VND virtual account onboarding document is uploaded with documentType=VA_ONBOARDING and currency=VND, then referenced in Create Virtual Account (see Guides / Virtual Account / VND Virtual Account Onboarding — Integration Guide).

Notes:

Request one URL per file. uploadUrl and fileId are one-to-one.

A 200 here only means the URL was issued. The file does not exist until your PUT returns 200; a fileId whose object was never uploaded is rejected by the consuming business API, not by this endpoint.

Accepted file types are pdf, jpg, jpeg, png, heic; a single file must be 10 KB – 10 MB. The consuming business API may apply further limits of its own.

fileType and fileSize are declared values. The real type and size are read from the stored object when the file is consumed, and a mismatch is rejected there.

Each fileId is bound to the merchant account that requested it and cannot be referenced by another merchant.

Request

Authorization

API Key

Add parameter in header

API-KEY

Example:

API-KEY: ********************

API Key

Add parameter in header

API-SIGNATURE

Example:

API-SIGNATURE: ********************

API Key

Add parameter in header

API-TIMESTAMP

Example:

API-TIMESTAMP: ********************

Body Params application/jsonRequired

Example

{
    "documentType": "VA_ONBOARDING",
    "fileType": "pdf",
    "fileSize": 284517,
    "currency": "VND"
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢200OK

application/json

Success or business error envelope; check status and data.

Bodyapplication/json

Examples

SuccessFailure

{
    "status": 200,
    "msg": "OK",
    "code": null,
    "data": {
        "fileId": "0f1c9a2e-5b34-4f0e-9a7a-1c2d3e4f5a6b",
        "uploadUrl": "https://s3.ap-southeast-1.amazonaws.com/bpn-files/files/10023/20260915/0f1c9a2e-5b34-4f0e-9a7a-1c2d3e4f5a6b.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20260915T070244Z&X-Amz-Expires=600&X-Amz-Signature=3a1f...",
        "expiresAt": "2026-09-15T07:12:44Z"
    },
    "traceId": "8f0a5b8c4e1f4d0e8f0a5b8c4e1f4d0e"
}