Installments API

Use Case

This API will be used to return with installment packages avalaibale for user

Request

POST/v2/installments/packages

Parameter	Type	Required	Description
merchantId	String		Fundiin provides MID as a unique identifier to each merchant.
lang	String		Language of returned message (vi or en)
amount.value	Number		The amount of the transaction
amount.currency	String		VND
firstInstallmentPercent	Double		The first amount user have to pay for an installment purchase, default is taking the lowest one
description	String		Description for the order.
items	JsonArray		Items

Data of each items

Attribute	Type	Required	Description
productId	String		The Id of item.
productName	String		The name of item.
description	String		The description of item.
category	String		The type of item.
currency	String		VND
quantity	Integer		Quantity number of each item. It must be greater than 0
price	Number		Price of single unit item
totalAmount	Number		price x quantity
imageUrl	String		Link image of product.

Example Request

{
    "merchantId": "Your merchant code",
    "lang": "vi",
    "description": "description",
    "firstInstallmentPercent" : 0.3,
    "amount": {
        "currency": "VND",
        "value": 1000000
    },
    "items": [
        {
            "id": "170594",
            "productId": "170594",
            "productName": "clothes",
            "quantity": 2,
            "price": 200000,
            "totalAmount": 400000,
            "purchaseAmount": 400000
        }
    ]
}

Response

Parameter	Type	Required	Description
merchantId	String		Fundiin provides MID as a unique identifier to each merchant.
responseTime	String		Date & Time of response: Format: YYYY-MM-DD hh:mm:ss
firstInstallmentPercent	String		The first amount user have to pay for an installment purchase
firstInstallments	JsonArray		List of the first amount user have to pay for an installment purchase
installmentPacks	JsonArray		This specifies packages for installments in the current provided in "firstInstallmentPercent" field.
resultStatus	String		Result status
resultMsg	String		The result message which contains information about the result.

Data of installmentPacks

Attribute	Type	Required	Description
packageId	String		The Id of package.
packageType	String		The type of package: 30_days,3_months, 6_months, 9_months, 12_months
firstInstallmentPercent	Double		The first percent user have to pay for an installment purchase
firstInstallmentAmount	Long		The first amount user have to pay for an installment purchase
subSeqInstallmentAmount	Long		The subsequent amounts the customer pay for an installment purchase.
interestRate	Double		The proportion of an installment that is charged
totalAmountDue	Long		The total amount on an installment purchase inclusive of fees and interest for the installment package
tenure	Integer		The number of tenure.
installmentFee	Long		Installment Fee

{
    "responseTime": "2023-08-03 04:10:14",
    "resultStatus": "APPROVED",
    "resultMsg": "The transaction was approved.",
    "merchantId": "your merchant code",
    "amount": {
        "currency": "VND",
        "value": 1000000
    },
    "firstInstallmentPercent": 0.3,
    "firstInstallments": [
        {
            "firstInstallmentPercent": 0.3,
            "firstInstallmentAmount": 300000
        },
        {
            "firstInstallmentPercent": 0.4,
            "firstInstallmentAmount": 400000
        },
        {
            "firstInstallmentPercent": 0.5,
            "firstInstallmentAmount": 500000
        },
        {
            "firstInstallmentPercent": 0.6,
            "firstInstallmentAmount": 600000
        },
        {
            "firstInstallmentPercent": 0.7,
            "firstInstallmentAmount": 700000
        }
    ],
    "installmentPacks": [
        {
            "packageId": "067000",
            "packageType": "6_months",
            "firstInstallmentPercent": 0.7,
            "firstInstallmentAmount": 700000,
            "subSeqInstallmentAmount": 53000,
            "interestRate": 0.05,
            "installmentFee": 15000,
            "totalAmountDue": 1015000,
            "tenure": 6
        },
        {
            "packageId": "097000",
            "packageType": "9_months",
            "firstInstallmentPercent": 0.7,
            "firstInstallmentAmount": 700000,
            "subSeqInstallmentAmount": 35000,
            "interestRate": 0.05,
            "installmentFee": 15000,
            "totalAmountDue": 1015000,
            "tenure": 9
        },
        {
            "packageId": "127000",
            "packageType": "12_months",
            "firstInstallmentPercent": 0.7,
            "firstInstallmentAmount": 700000,
            "subSeqInstallmentAmount": 27000,
            "interestRate": 0.05,
            "installmentFee": 15000,
            "totalAmountDue": 1015000,
            "tenure": 12
        }
    ]
}

Result Status & Messages

Status code	Description	Action to take
APPROVED	The transaction was successfully initialized.	Proceed with the transaction 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_FIRST_INSTALLMENT_PERCENT	The first installment percent is invalid.	Please retry with a correct firstInstallmentPercent.
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.
AMOUNT_EXCEEDED_UPPER_LIMIT	The payment amount exceeds the limit at the merchant level or account level.	Ensure that the payment amount is within the specified limit.
AMOUNT_BELOW_MINIMUM_LIMIT	The payment amount is below the minimum limit.	Increase the payment amount to meet the minimum limit.
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.
INSTALLMENT_UNAVAILABLE	The installment package information is invalid.	Verify the installment package information provided and correct any errors.
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.