Initiate Transaction API

Flow diagram

Flow diagram for payment processing via API

Use Case

This API will be used to create a transaction

Request

POST /v2/payments

Parameter	Type	Required	Description
merchantId	String		Fundiin provides MID as a unique identifier to each merchant.
referenceId	String		Unique identifier generated by the merchant for this charge transaction REGEX: ^[0-9a-zA-Z_:-]60$
storeId	String		The store Id that is processing the payment
requestType	String		installment
lang	String		Language of returned message (vi or en), If not included, the default is en.
extraData	String		Additional data, defined by Merchant
paymentMethod	String		APP, POS, WEB.
terminalType	String		The terminal type of which the merchant service applies to. DESKTOP_BROWSER, MOBILE_BROWSER, MOBILE_APP
description	String		Description for the order.
successRedirectUrl	String		Redirect to this url after successful
unSuccessRedirectUrl	String		Redirect to this url after unsuccessful
amount.value	Number		The amount of the transaction
amount.currency	String		VND
installment	JsonObject		InstallmentInfo
items	JsonArray		Maximum: 200 items. Items
orderHistory	JsonArray		Merchant's order history (10 most recent orders). Maximum: 10 orders Order History
customer	JsonObject		User information contains user details like email, phone number etc. Customer Info
seller	JsonObject		Seller information contains seller details like email, phone number etc. Seller Info
shipping	JsonObject		This contain the shipping info for an order. Shipping Info
sendSms	Boolean		Flag whether SMS to be sent to customer by Fundiin.
sendEmail	Boolean		Flag whether Email to be sent to customer by Fundiin.

Data of installment

Attribute	Type	Required	Description
packageId	String

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.

Data of customer

Attribute	Type	Required	Description
phoneNumber	String		Mobile number of user. number must have size equals 10 or 11. 096, 0164
rank	String		Customer segmentation.
description	String		Description of the customer.
email	String		Valid email of the user.
firstName	String		The first name.
lastName	String		The last name.
gender	String		The following values are permitted: M : Male, F: Female, U: UNKNOWN.
dateOfBirth	String		The customer's date of birth. Format ISO-8601: DD-MM-YYYY

Data of seller

Attribute	Type	Required	Description
id	String		Seller Id, Unique identifier generated by the merchant for this seller
email	String		Valid email of the user.
name	String		Seller Name.
address	String		Address of seller

Data of shipping

Attribute	Type	Required	Description
city	String		The city of address Shipping.
zipCode	String		The zipCode of address Shipping.
district	String		The district of address Shipping.
ward	String		The ward of address Shipping.
street	String		The street of address Shipping.
streetNumber	String		The streetNumber of address Shipping.
houseNumber	String		The houseNumber of address Shipping.
houseExtension	String		The houseExtension of address Shipping.
country	String		The country of address Shipping.

Data of each orderHistory

Attribute	Type	Required	Description
orderId	String		The Id of order..
amount	String		The total amount of order.
paymentMethod	String		CARD, WALLET, BANK TRANSFER, COD, PGW
purchasedAt	String		Time the order was placed. Format ISO-8601 DD-MM-YYYY
status	String		Status of the order PROCESSING, SUCCESS, FAIL, CANCELED, REFUNDED

Example Request

{
    "merchantId": "Your merchant code",
    "referenceId": "Your order number",
    "storeId": "Your store id",
    "requestType": "onetime",
    "patmentMethod": "paymentMethod",
    "lang": "vi",
    "extraData": "jsonstring", 
    "description": "description", 
    "successRedirectUrl": "domain.com",
    "unSuccessRedirectUrl": "domain.com",
    "installment": {
        "packageId": "packageId"
    },
    "amount": {
        "currency": "VND",
        "value": 400000
    },
    "items": [
        {
            "productId": "170594",
            "productName": "clothes",
            "description": "Red",
            "quantity": 2,
            "price": 200000,
            "currency": "VND",
            "totalAmount": 400000
        }
    ],
    "customer": {
        "phoneNumber": "0912345678",
        "email": "youremail@email.com",
        "firstName": "Doe",
        "lastName": "Test",
        "gender": "F",
        "dateOfBirth": "17-04-1999"
    },
    "shipping": {
        "city": "Ho Chi Minh",
        "zipCode": "00700",
        "district": "5",
        "ward": "",
        "street": "Tran Nhan Ton",
        "streetNumber": "Apt 214",
        "houseNumber": null,
        "houseExtension": null,
        "country": "VN"
    }
}

Response

Parameter	Type	Required	Description
merchantId	String		Identification of the merchant that was issued when registering with Fundiin.
referenceId	String		Order number for the charge transaction.
responseTime	String		Date & Time of response: Format: YYYY-MM-DD hh:mm:ss
resultStatus	String		Result status
resultMsg	String		The result message which contains information about the result.
paymentUrl	String		Payment URL
qrData	String		Qr Code Data

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",
    "responseTime": "2023-07-24 09:33:55",
    "resultMsg": "Thành công",
    "resultStatus": "APPROVED",
    "paymentUrl": "https://fundiin.vn/v2/payment",
    "qrData": "https://fundiin.vn/v2/payment"
}

Result Status & Messages

Status code	Description	Action to take
APPROVED	The transaction was successfully initialized.	Proceed with the transaction as normal.
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.
INVALID_STORE_ID	The storeId is invalid.	Please retry with a correct storeId.
DUPLICATE_REFERENCE_ID	The referenceId is duplicated.	You can inquire about this referenceId in transaction status, or retry with a different referenceId.
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.
PHONE_NUMBER_UNAVAILABLE	Phone number is unavailable.	Make sure the length of the phone number equals 10 or 11.
PHONE_NUMBER_INVALID	Phone number is invalid.	Provide a valid phone number.
AMOUNT_EXCEEDED_UPPER_LIMIT	The payment amount exceeds the limit at the merchant level or account level.	Adjust the payment amount to be 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.
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.