Upload Invoice API

Use Case

This API is used by the Merchant to upload an invoice file (image/PDF/XML) for an order (referenceId) after confirming a payment.
A maximum of 3 invoices can be uploaded per referenceId.

Call this API only after confirming payment or receiving a Payment Notification from Fundiin.

Request

POST /v2/payments/upload-invoice

Content-Type: multipart/form-data

Parameter	Type	Required	Description
merchantId	String		Fundiin Merchant ID (MID).
referenceId	String		Order ID, must match the value used in Initiate API.
paymentTransId	String		Fundiin Payment Transaction ID (if available).
storeId	String		Store ID where payment was processed (required for in-store).
invoiceNumber	String		Merchant/POS invoice number.
invoiceDate	String		ISO-8601 UTC (e.g., 2025-08-28T03:10:05Z).
file	File		Upload file (jpg, png, pdf, xml max 5MB). Either file or fileUrl must be provided. If both are sent, file will be used.
fileUrl	String		Public/signed URL (https://...) to invoice file (jpg/png/pdf). Either file or fileUrl must be provided.
description	String		Extra notes about the invoice.
extraData	String		Merchant-defined extra data (JSON string).

Signature generation

For this API, the Signature is calculated only over the required textual fields listed below. Merchants must build the canonical string strictly by following these fields in order:

merchantId=$merchantId&referenceId=$referenceId&paymentTransId=$paymentTransId&storeId=$storeId&invoiceNumber=$invoiceNumber&invoiceDate=$invoiceDate&description=$description&extraData=$extraData

Then:

Signature = HMAC_SHA256(secret, canonical_string) -> hex string

Merchant must send this in the Signature field.

---

Example Request (upload file)

curl -X POST "https://api.fundiin.vn/v2/payments/upload-invoice" \
  -H "Content-Type: multipart/form-data" \
  -H "Client-Id: YOUR_MID" \
  -H "Request-Time: 2025-08-26 10:12:45" \
  -H "Signature: <hex_hmac>" \
  -F 'merchantId=YOUR_MID' \
  -F 'referenceId=ORD82A0DBCC' \
  -F 'paymentTransId=PAY1ED3BE97' \
  -F 'storeId=SG-GIGAMALL-01' \
  -F 'invoiceNumber=INV-2025-000123' \
  -F 'invoiceDate=2025-08-28T03:10:05Z' \
  -F 'description=Customer requested tax invoice' \
  -F 'extraData={"posShift":"A1"}' \
  -F 'file=@/path/to/invoice.pdf;type=application/pdf'

Example Request (upload by URL)

curl -X POST "https://api.fundiin.vn/v2/payments/upload-invoice" \
  -H "Content-Type: multipart/form-data" \
  -H "Client-Id: YOUR_MID" \
  -H "Request-Time: 2025-08-26 10:12:45" \
  -H "Signature: <hex_hmac>" \
  -F 'referenceId=ORD82A0DBCC' \
  -F 'paymentTransId=PAY1ED3BE97' \
  -F 'fileUrl=https://merchant-cdn.com/invoices/inv-123.pdf' \
  -F 'invoiceNumber=INV-2025-000123' \
  -F 'invoiceDate=2025-08-28T03:10:05Z' \
  -F 'description=Invoice stored in merchant CDN'

---

Response

Parameter	Type	Required	Description
referenceId	String		Order ID.
invoiceId	String		Invoice file ID.
paymentTransId	String		Fundiin Payment Transaction ID (if provided/matched).
uploadedAt	String		ISO-8601 UTC timestamp of upload.
resultStatus	String		Result status
resultMsg	String		Result message.

Example Response

{
  "referenceId": "ORD82A0DBCC",
  "invoiceId": "INV_FILE_f7e1c2f9",
  "paymentTransId": "PAY1ED3BE97",
  "uploadedAt": "2025-08-26T10:12:45Z",
  "resultStatus": "APPROVED",
  "resultMsg": "Invoice stored successfully.",
}

---

Result Status & Messages

Status code	Description	Action to take
APPROVED	Upload successful.	No further action.
ACCESS_DENIED	Access denied.	Check Merchant config / Authorization.
INVALID_REQUEST	Invalid request (missing fields, wrong format, bad JSON, etc.).	Fix request and retry.
INVALID_REFERENCE_ID	referenceId does not exist or mismatch.	Verify and retry.
INVALID_STORE_ID	storeId invalid (when required).	Use a valid storeId.
INVALID_FILE_TYPE	File type not supported. Only image/jpeg, image/png, application/pdf, application/xml are accepted. If using fileUrl, it must point to a valid file with one of these types/extensions.	Use a supported file format and retry.
FILE_TOO_LARGE	File size exceeds 5 MB.	Reduce file size and retry.
LIMIT_EXCEEDED	More than 3 invoices uploaded for this referenceId.	Remove some via portal/support, or skip.
ERROR_GENERAL	Other error.	Contact Fundiin Support.

---