Confirm In-Store Payment API

Use Case

This API is used by the Merchant to confirm that the down payment has been collected in store.

Call this API only after receiving a Payment Notification from Fundiin where paymentMethod = STORE and downPaymentAmount is present.

Request

POST /v2/payments/confirm-store

Parameter	Type	Required	Description
merchantId	String		Fundiin-provided Merchant ID (MID) as a unique identifier for the merchant.
referenceId	String		Unique identifier of the order to confirm payment for. Must match the value used in Initiate API.
storeId	String		Store ID where the payment was processed.
downPaymentAmount.value	Number		Amount of the down payment collected from the customer at the store.
downPaymentAmount.currency	String		Currency of the down payment amount. Always VND.
tenderType	String		Payment tender type. Possible values: CASH, CARD, BANK_TRANSFER, WALLET.
storePaymentRef	String		Merchant/POS transaction ID for the payment.
cashierId	String		Identifier for the cashier handling the transaction.
description	String		Additional description for this payment.
extraData	String		Additional merchant-defined data.

Example Request

{
    "merchantId": "Your merchant code",
    "storeId": "Your store id",
    "referenceId": "Your order number",
    "downPaymentAmount": {
        "currency": "VND",
        "value": 100000
    },
    "tenderType": "CASH",
    "storePaymentRef": "POS-123456",
    "cashierId": "NV001",
    "description": "Paid in full",
    "extraData": "{\"promoCode\":\"DISCOUNT10\"}"
}

Response

Parameter	Type	Required	Description
referenceId	String		Reference ID (order number) of the transaction.
resultStatus	String		APPROVED, REQUEST_PROCESSING, or error codes (see table below).
resultMsg	String		Result message containing additional info.
paymentTransId	String		Fundiin Payment Transaction ID generated after confirmation.
paymentStatus	String		PENDING, SUCCESS, FAIL.
paymentTime	String		ISO-8601 UTC time the payment was made. Example: 2025-08-08T03:10:05Z.

Example Response

{
    "referenceId": "ORD123",
    "resultStatus": "APPROVED",
    "resultMsg": "The payment was successfully confirmed.",
    "paymentTransId": "PAYABC123",
    "paymentStatus": "SUCCESS",
    "paymentTime": "2025-08-08T03:10:05Z",
}

---

Result Status & Messages

Status code	Description	Action to take
APPROVED	The payment was successfully confirmed.	No further action needed.
REQUEST_PROCESSING	The confirmation request has already been processed or is in progress.	Retry later with the same Idempotency-Key.
ACCESS_DENIED	Access denied.	Check merchant configuration in portal or contact Fundiin.
INVALID_REQUEST	Invalid request (missing/invalid parameters).	Fix request and retry.
INVALID_REFERENCE_ID	The referenceId is invalid.	Verify and retry.
INVALID_STORE_ID	The storeId is invalid.	Retry with a correct storeId.
AMOUNT_MISMATCH	Confirmed amount does not match initiated order amount.	Correct the amount or contact support.
EXPIRED	Order expired, cannot confirm.	Initiate a new transaction.
ERROR_GENERAL	Declined due to general reasons other than the specific decline codes provided.	Contact Fundiin support for assistance.