Skip to main content
Merchant Integration / Checkout APIs

Initiate Transaction

Create a Fundiin payment transaction with order, customer, amount, redirect, and installment data.

Open Spec
Endpoint

POST/v2/payments

DirectionMerchant to Fundiin
Content typeapplication/json
Versionv2 latest
Request Parameters

Required and optional fields

Request parameters

Required
merchantIdStringRequired
Fundiin-provided MID.
storeIdStringRequired
Store ID processing the payment.
referenceIdStringRequired
Unique merchant reference. Regex: ^[0-9a-zA-Z_:-]{1,60}$.
platformIdStringRequired
Platform or third party processing the order/payment service.
requestTypeStringRequired
Use installment.
paymentMethodStringRequired
APP, POS, or WEB.
descriptionStringRequired
Order description.
successRedirectUrlStringRequired
Redirect URL after successful payment.
unSuccessRedirectUrlStringRequired
Redirect URL after unsuccessful payment.
amount.valueNumberRequired
Transaction amount in VND minor unit.
amount.currencyStringRequired
Currency. Use VND.
itemsJsonArrayRequired
Order items. Maximum 200 items.
customerJsonObjectRequired
Customer information.
shippingJsonObjectRequired
Shipping information.
Optional
langStringOptional
vi or en. Defaults to en.
extraDataStringOptional
Merchant-defined extra data.
terminalTypeStringOptional
DESKTOP_BROWSER, MOBILE_BROWSER, or MOBILE_APP.
installmentJsonObjectOptional
Installment package information.
sellerJsonObjectOptional
Seller information.
transExpiredTimeNumberOptional
Maximum time for the customer to complete payment, in milliseconds.
sendSmsBooleanOptional
Whether Fundiin should send SMS to customer.
sendEmailBooleanOptional
Whether Fundiin should send email to customer.

installment

Required
packageIdStringRequired
Installment package ID.

items[]

Required
productIdStringRequired
The item ID.
productNameStringRequired
The item name.
categoryStringRequired
The item category.
currencyStringRequired
Currency. Use VND.
quantityIntegerRequired
Item quantity. Must be greater than 0.
priceNumberRequired
Single unit price.
totalAmountNumberRequired
price x quantity.
Optional
descriptionStringOptional
Item description.
imageUrlStringOptional
Product image URL.

customer

Required
phoneNumberStringRequired
Customer mobile number. Usually 10 or 11 digits.
emailStringRequired
Valid customer email.
firstNameStringRequired
Customer first name.
lastNameStringRequired
Customer last name.
Optional
rankStringOptional
Customer segmentation.
descriptionStringOptional
Customer description.
genderStringOptional
M, F, or U.
dateOfBirthStringOptional
Format DD-MM-YYYY.

seller

Required
idStringRequired
Seller ID generated by the merchant.
Optional
emailStringOptional
Seller email.
nameStringOptional
Seller name.
addressStringOptional
Seller address.

shipping

Required
cityStringRequired
Shipping city.
districtStringRequired
Shipping district.
wardStringRequired
Shipping ward.
streetStringRequired
Shipping street.
houseNumberStringRequired
House number.
countryStringRequired
Shipping country. Use VN.
Optional
zipCodeStringOptional
Shipping ZIP code.
streetNumberStringOptional
Street number.
houseExtensionStringOptional
House extension.
HTTP Responses

Response body

Response parameters

merchantIdStringRequired
Merchant identifier issued by Fundiin.
referenceIdStringRequired
Merchant order/reference number.
responseTimeStringRequired
Response date time. Format YYYY-MM-DD hh:mm:ss.
resultStatusStringRequired
Result status.
resultMsgStringRequired
Result message.
paymentUrlStringRequired
Fundiin payment URL.
qrDataStringOptional
QR code data.
Result Status

Status codes and actions

APPROVED
The request was approved.Continue the integration flow.
ACCESS_DENIED
Access denied.Check merchant configuration or contact Fundiin.
INVALID_REQUEST
The request is invalid.Fix request fields and retry.
INVALID_REFERENCE_ID
referenceId is invalid.Retry with a valid referenceId.
INVALID_STORE_ID
The storeId is invalid.Retry with a correct storeId.
DUPLICATE_REFERENCE_ID
The referenceId is duplicated.Query transaction status or retry with another referenceId.
INVALID_CLIENT_ID
clientId is not registered.Use a valid registered clientId.
INVALID_SIGNATURE
The HMAC signature is invalid.Recompute the signature with the correct secret key and request body.
INVALID_MERCHANT_ID
Merchant is not registered.Verify the merchant ID.
INVALID_HTTP_METHOD
HTTP method is invalid.Use the documented method.
INVALID_API
API is not defined.Check the request URL and endpoint.
INVALID_AMOUNT
Payment amount is invalid.Verify the payment amount.
PHONE_NUMBER_UNAVAILABLE
Phone number is unavailable.Provide a phone number with the documented length.
PHONE_NUMBER_INVALID
Phone number is invalid.Provide a valid phone number.
AMOUNT_EXCEEDED_UPPER_LIMIT
Payment amount exceeds the configured limit.Adjust the amount or contact Fundiin.
AMOUNT_BELOW_MINIMUM_LIMIT
Payment amount is below the minimum limit.Increase the amount or contact Fundiin for configuration.
REQUEST_PROCESSING
The request was already processed or is in progress.Monitor status or retry later.
DOWNSTREAM_ERROR
Partner downstream timeout.Retry later as the issue may be temporary.
ERROR_GENERAL
Declined due to a general error.Contact Fundiin support if the issue persists.
Endpoint destination URL

Fundiin host

POSThttps://gateway-sandbox.fundiin.vn/v2/payments
Authentication

Headers

HMAC guide
Content-Typeapplication/json
Client-IdYOUR_CLIENT_ID
Request-TimeYYYY-MM-DD hh:mm:ss
SignatureHMAC_SHA256(request_body, secretKey)
Idempotency-KeyRecommended for safe retries
cURL

Sandbox-ready request

curl --request POST 'https://gateway-sandbox.fundiin.vn/v2/payments' \  --header 'Content-Type: application/json' \  --header 'Client-Id: YOUR_CLIENT_ID' \  --header 'Request-Time: YYYY-MM-DD hh:mm:ss' \  --header 'Signature: HMAC_SHA256_REQUEST_BODY' \  --header 'Idempotency-Key: ORDER-20260621-001' \  --data-raw '{"merchantId":"Your merchant code","referenceId":"Your order number","storeId":"Your store id","platformId":"Your platform id","requestType":"installment","paymentMethod":"WEB","terminalType":"DESKTOP_BROWSER","lang":"vi","extraData":"jsonstring","description":"description","successRedirectUrl":"https://merchant.example/success","unSuccessRedirectUrl":"https://merchant.example/failed","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","rank":"standard","description":"Customer description","email":"youremail@email.com","firstName":"Doe","lastName":"Test","gender":"F","dateOfBirth":"17-04-1999"},"seller":{"id":"SELLER-001","email":"seller@example.com","name":"Seller Name","address":"Ho Chi Minh"},"shipping":{"city":"Ho Chi Minh","zipCode":"00700","district":"5","ward":"","street":"Tran Nhan Ton","streetNumber":"Apt 214","houseNumber":"214","houseExtension":"","country":"VN"},"transExpiredTime":1800000,"sendSms":true,"sendEmail":true}'
Request Example

JSON

{  "merchantId": "Your merchant code",  "referenceId": "Your order number",  "storeId": "Your store id",  "platformId": "Your platform id",  "requestType": "installment",  "paymentMethod": "WEB",  "terminalType": "DESKTOP_BROWSER",  "lang": "vi",  "extraData": "jsonstring",  "description": "description",  "successRedirectUrl": "https://merchant.example/success",  "unSuccessRedirectUrl": "https://merchant.example/failed",  "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",    "rank": "standard",    "description": "Customer description",    "email": "youremail@email.com",    "firstName": "Doe",    "lastName": "Test",    "gender": "F",    "dateOfBirth": "17-04-1999"  },  "seller": {    "id": "SELLER-001",    "email": "seller@example.com",    "name": "Seller Name",    "address": "Ho Chi Minh"  },  "shipping": {    "city": "Ho Chi Minh",    "zipCode": "00700",    "district": "5",    "ward": "",    "street": "Tran Nhan Ton",    "streetNumber": "Apt 214",    "houseNumber": "214",    "houseExtension": "",    "country": "VN"  },  "transExpiredTime": 1800000,  "sendSms": true,  "sendEmail": true}
Response Example

JSON

{  "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"}
PostmanIdempotencyWebhooksTest Instruments