Create tokenizations Request API

Use Case

This API will be used to create a linked tokenizations request

Request

POST /v2/tokenizations

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$
merchantUserId	String		Unique identifier merchant customer
storeId	String		Store Id
requestType	String		`AUTHENTICATION`
lang	String		Language of returned `message` (`vi` or `en`), If not included, the default is `en`.
extraData	String		Additional data, defined by Merchant
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	Integer		The amount of the transaction, Send 0 to only linked token
amount.currency	String		`VND`
installment	JsonObject		InstallmentInfo
items	JsonArray	amount > 0	Items
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

Data of installment

Attribute	Type	Required	Description
packageId	String

Data of each items

Attribute	Type	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	Integer	Price of single unit item
totalAmount	Integer	`price` x `quantity`
imageUrl	String	Link image of product.

Data of customer

Attribute	Type	Description
phoneNumber	String	mobile number of user.
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	Integer	The customer's date of birth. Format ISO-8601: `DD-MM-YYYY`

Data of seller

Attribute	Type	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

Example Request

{
    "merchantId": "Your merchant code",
    "referenceId": "Your order number",
    "storeId": "Your store id",
    "merchantUserId": "MerchantUserId_123",
    "requestType": "AUTHENTICATION",
    "lang": "vi",
    "extraData": "jsonstring", 
    "description": "description", 
    "successRedirectUrl": "domain.com",
    "unSuccessRedirectUrl": "domain.com",
    "installment": {
        "packageCode": "packageCode"
    },
    "amount": {
        "currency": "VND",
        "value": 1000
    },
    "items": [
        {
            "id": "170594",
            "productId": "170594",
            "productName": "clothes",
            "quantity": 2,
            "price": 200000,
            "totalAmount": 400000, //price x quantity
            "purchaseAmount": 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	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.
redirectUrl	String	Fundiin redirect URL, user access url to authenication and pay
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",
    "redirectUrl": "https://fundiin.vn/v2/tokens",
    "qrData": "https://fundiin.vn/v2/tokens"
}

Result Status & Messages

Status code	Description	Action to take
APPROVED	The transaction was successfully initial.
ACCESS_DENIED	Access denied.	Please check your settings in merchant portal, or contact Fundiin for configurations.
MERCHANT_USER_ID_INVALID	The merchantUserId is required	Please send Fundiin merchantUserId because this is required.
INVALID_REQUEST	Invalid request. e.g. Invalid currency, invalid amout 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 inquiry this referenceId in transaction status, or retry with a different referenceId.
INVALID_CLIENT_ID	The cliendId 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.
AMOUNT_EXCEEDED_UPPER_LIMIT	The payment amount exceeds the limit at merchant level or account level
AMOUNT_BELOW_MINIMUM_LIMIT	The payment amount is below minimun limit.
REQUEST_PROCESSING	The request already processed or in 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.

Use Case​

Request​

Data of installment​

Data of each items​

Data of customer​

Data of seller​

Response​

Result Status & Messages​