Refund API

Use Case

Refund API to initiate a refund of a successful payment.

When you are create a refund you need to provide the Refund Amount and the Payment Transaction ID

Request

POST/v2/payments/refund

Parameter	Type	Required	Description
merchantId	String		Fundiin provides MID as a unique identifier to each merchant.
referenceId	String		It is unique reference ID for a transaction passed in the transaction request. Duplicate referenceId will be rejected by the Fundiin gateway. it's not referenceId of the original purchase transaction
paymentTransId	String		The ID of the payment to be refunded paymentTransId is provided in notification result payment / Query Status
lang	String		Language of returned message (vi or en)
description	String		The reasons for the refund.
amount.value	Number		The amount for the refund.
amount.currency	String		VND

Example Request

{
    "merchantId": "Your merchant code",
    "referenceId": "Your order number",
    "paymentTransId": "payment trans Id",
    "lang": "vi",
    "description": "description",
    "amount": {
        "currency": "VND",
        "value": 1000
    }
}

Response

Parameter	Type	Required	Description
merchantId	String		Fundiin provides MID as a unique identifier to each merchant.
referenceId	String		Merchant's Reference Id unique for every transaction
responseTime	String		Date & Time of response: Format: YYYY-MM-DD hh:mm:ss
amount.value	Number		The amount for the refund.
amount.currency	String		VND
refundTransId	String		This parameter is returned by Fundiin if the refund succeeds
resultStatus	String		Result status
resultMsg	String		The result message which contains information about the result.

By default expiry time for the order created is 30 minutes from order creation time stamp. If this needs to be extended for more than 30 minutes please contact Fundiin.

{
    "merchantId": "FundiinVN",
    "referenceId": "Your order number",
    "amount": 100000,
    "refundTransId": "3123123123123",
    "responseTime": 1689315609,
    "resultMsg": "Thành công",
    "resultStatus": "APPROVED"
   
}

Result Status & Messages

Status code	Description	Action to take
APPROVED	Refund was approved.	Proceed with the refund process as it has been approved.
ACCESS_DENIED	Access denied.	Please check your settings in the merchant portal or contact Fundiin for configurations.
INVALID_REQUEST	Invalid request. e.g., Invalid currency, invalid amount, etc.	Ensure that the request parameters are correct and meet the API requirements.
INVALID_REFERENCE_ID	The referenceId is invalid.	Please retry with a different referenceId.
DUPLICATE_REFERENCE_ID	The referenceId is duplicated.	You can inquire about this referenceId in transaction status, or retry with a different referenceId.
PAYMENT_NOT_EXIST	Refund was declined because the original transaction does not exist.	The payment transaction does not exist. Check the payment status manually.
PAYMENT_NOT_COMPLETE	Refund was declined because the original transaction is not completed.	The payment transaction does not exist. Check the payment status manually.
INVALID_CLIENT_ID	The clientId is not registered.	Make sure to use a valid and registered clientId for the request.
INVALID_SIGNATURE	The signature is invalid.	Double-check the signature generation process to ensure its correctness.
INVALID_MERCHANT_ID	The merchant is not registered.	Ensure that the merchant ID is correct and registered with Fundiin.
INVALID_HTTP_METHOD	The server does not implement the requested HTTPS method.	Use the correct HTTP method (e.g., GET, POST, etc.) when making the request.
INVALID_API	API is not defined.	Check whether the request URL is correct. Ensure that the endpoint of the called API is correct.
INVALID_AMOUNT	Payment amount is invalid.	Verify the payment amount and provide a valid amount.
REFUND_AMOUNT_EXCEEDED	The refund amount exceeds the payment amount.	Ensure that the refund amount is within the payment amount limit.
REFUND_AMOUNT_LOWER	The refund amount is lower than the payment amount.	Ensure that the refund amount is equal to or greater than the payment amount.
PERMISSION_DENIED	Permission to make the payment is denied.	Review and update permissions to allow the payment to proceed.
REQUEST_PROCESSING	The request has already been processed or is in progress.	Monitor the transaction status or take appropriate action based on the current progress.
DOWNSTREAM_ERROR	Partner downstream timeout. (Retriable)	Retry the request later, as the error might be temporary due to partner-related issues.
ERROR_GENERAL	Declined due to general reasons other than the specific decline error codes provided.	Contact Fundiin support for assistance in identifying and resolving the general issue.