VCC File Upload API

Upload an identity document before creating or updating a cardholder.

Endpoint

Sandbox

POST https://api.futurepay-develop.com/api/v1/issuing/reference/upload

Production

POST https://api.futurepay.global/api/v1/issuing/reference/upload

Content-Type

multipart/form-data

Request Headers

Header	Type	Required	Description
Authorization	string	Yes	Merchant API secret key in the format `Bearer YOUR_SECRET_KEY`.
merchantId	string	Yes	Merchant ID. The merchant must be enabled and activated, with VCC product access enabled.
appId	string	Yes	An enabled application ID assigned to the same merchant.
Content-Type	string	Yes	`multipart/form-data` with a boundary generated by the HTTP client.

Use the credentials assigned to the selected environment. The secret key, merchant ID and application ID must belong to the same merchant.

Request Parameters

Send the parameters as form-data.

Parameter	Type	Required	Description
file	file	Yes	One non-empty file with a filename. Supported extensions: `.jpg`, `.jpeg`, `.png`, `.pdf` (case-insensitive). Maximum file size: 20 MB (20,971,520 bytes). The extension must match the file content type.

Upload the front and back of an identity document using separate requests. Each request accepts one file.

Request Example

Headers

Key	Value
Authorization	Bearer YOUR_SECRET_KEY
merchantId	YOUR_MERCHANT_ID
appId	YOUR_APP_ID

form-data

Key	Value
file	front.png

curl

curl --request POST \
  'https://api.futurepay-develop.com/api/v1/issuing/reference/upload' \
  --header 'Authorization: Bearer YOUR_SECRET_KEY' \
  --header 'merchantId: YOUR_MERCHANT_ID' \
  --header 'appId: YOUR_APP_ID' \
  --form 'file=@/path/to/front.png'

Replace /path/to/front.png with the local file location. For production, use the production endpoint and credentials.

When using curl --form, let curl generate the Content-Type header and multipart boundary. For other HTTP clients, use their multipart upload builder to generate both.

Response

Field	Type	Description
code	string	Result code. `0` indicates a successful upload.
msg	string	Result message.
serverTime	string	Server timestamp in milliseconds since the Unix epoch.
success	boolean	Whether the request succeeded.
data.path	string	Generated filename used to reference the uploaded file in subsequent cardholder requests. This is not a public URL or a full storage path.

Response Example

{
  "code": "0",
  "msg": "succeeded",
  "serverTime": "1794032836992",
  "success": true,
  "data": {
    "path": "37f9be70bca3462e89cbef4addd73a4d.png"
  }
}

The returned filename is generated by the server and may differ from the original filename. Always use the exact returned value.

Use the Uploaded File

Pass the returned path as individual.idDocFrontPath or individual.idDocBackPath when creating or updating a cardholder.

Example document fields:

{
  "individual": {
    "idDocFrontPath": "37f9be70bca3462e89cbef4addd73a4d.png",
    "idDocBackPath": "fedcba9876543210fedcba9876543210.png"
  }
}

This example shows only the document fields. Include the other required fields for the target operation. See the Cardholder API for the full request structure.

Each file can only be referenced by the merchant that uploaded it. A file uploaded by another merchant cannot be used, even if its filename is known.

Error Codes

Code	Description
`400`	A required header or file parameter is missing, or a request parameter has an invalid format. Check `msg` for details.
`REQUEST_HEADER_MERCHANT_ID_MISSING`	The `merchantId` header is missing.
`REQUEST_HEADER_MERCHANT_ID_INVALID`	The merchant ID is invalid.
`API_APP_ID_INVALID`	The application ID is invalid, disabled, or does not match an eligible application for the merchant.
`API_UPLOAD_AUTH_INVALID`	The Bearer credentials are invalid.
`MERCHANT_NOT_EXIST`	The merchant does not exist.
`MERCHANT_STATUS_INVALID`	The merchant is disabled or has not been activated.
`VCC_PRODUCT_NOT_ENABLED`	The merchant's VCC product access is not enabled.
`API_FILE_REQUIRED`	The file is empty.
`API_FILE_NAME_REQUIRED`	The filename is empty.
`API_FILE_TOO_LARGE`	The file exceeds 20 MB (20,971,520 bytes).
`API_FILE_TYPE_INVALID`	The file extension or content type is not supported.
`API_FILE_TYPE_MISMATCH`	The file extension does not match the content type.
`API_FILE_UPLOAD_FAILED`	The upload could not be completed. Retry later.

Error Response Example

{
  "code": "API_FILE_TYPE_INVALID",
  "msg": "Only jpg, jpeg, png and pdf files are supported",
  "serverTime": "1794032836992",
  "success": false
}

When a filename is submitted to a cardholder API, an unknown or inaccessible file reference returns API_FILE_NOT_FOUND with the message File not found or not accessible.