Create pay-in
POST
/trade/payment/createRequest headers
Payment method values
| paymentType |
|---|
QR |
VA |
Request parameters
| Field | Type | Required | Maximum length | Description |
|---|---|---|---|---|
merchantOrderNo | String | Yes | 32 | Merchant order number |
transactionAmount | String | Yes | 20 | Pay-in amount in VND, integers only |
paymentType | String | Yes | 24 | Payment method |
idType | String | No | 32 | Optional ID type. This endpoint has no fixed enum; omit this field unless required by your business or payment channel. |
userIdCard | String | No | 50 | ID number. No fixed format; omit this field unless required by your business or payment channel. |
userName | String | Yes | 64 | Payer name |
userPhone | String | Yes | 50 | Phone number: 10 digits starting with 0 |
userEmail | String | Yes | 50 | Payer email; must match a valid email address format |
bankCode | String | Conditional | 50 | Bank code; see the bank list; required when paymentType is VA |
bankAccountNo | String | No | 64 | Bank account number |
merchantName | String | No | 64 | Payee name |
description | String | No | 100 | Description |
expireTime | String | No | - | Order expiration time (local time, format yyyy-MM-dd HH:mm:ss) |
paymentCallbackUrl | String | No | 200 | Pay-in callback URL |
Request example
The following example shows the field structure. Before submitting, replace paymentType with the value confirmed by your VellPay representative.
{ "merchantOrderNo": "ORDER202609170001", "transactionAmount": "100000", "paymentType": "QR", "idType": "NATIONAL_ID", "userIdCard": "012345678901", "userName": "TEST USER", "userPhone": "0912345678", "userEmail": "user@example.com", "bankCode": "1001", "bankAccountNo": "1234567890", "merchantName": "TEST MERCHANT", "description": "Payment order", "expireTime": "2026-09-21 18:00:00", "paymentCallbackUrl": "https://merchant.example/callback"}VA request example (bankCode is required):
{ "merchantOrderNo": "ORDER202609170002", "transactionAmount": "100000", "paymentType": "VA", "userName": "TEST USER", "userPhone": "0912345678", "userEmail": "user@example.com", "bankCode": "1001", "paymentCallbackUrl": "https://merchant.example/callback"}Response parameters
| Field | Type | Required | Maximum length | Description |
|---|---|---|---|---|
code | int | Yes | - | Status code; a value other than 200 indicates an error |
data | Object | Yes | - | Response body |
data.merchantOrderNo | String | Yes | 32 | Merchant order number |
data.tradeNo | String | Yes | 32 | Platform order number |
data.transactionAmount | String | Yes | - | Pay-in amount in VND, integers only |
data.status | String | Yes | 24 | Order status: PAYING (paying) or FAIL (failed) when created |
data.paymentType | String | Yes | 24 | Payment method |
data.failMsg | String | No | 200 | Order failure reason; returned on failure |
data.paymentInfo | String | Yes | 200 | Primary payment information: QR returns the QR code string; VA returns the VA account number |
data.additional | Object | No | - | Additional payment information: paymentLink (String, required) is the payment link; qrString (String, required) is the QR code string for QR; va (String, required) is the VA account number for VA |
msg | String | No | - | Error message |
tid | String | Yes | - | Trace ID |
Response example
{ "code": 200, "data": { "merchantOrderNo": "ORDER202609170001", "tradeNo": "VS2608270002VN0000000000040059", "transactionAmount": "100000", "status": "PAYING", "paymentType": "QR", "paymentInfo": "QR_CODE_STRING_EXAMPLE", "additional": { "paymentLink": "https://example.com/pay", "qrString": "QR_CODE_STRING_EXAMPLE", "va": "1234567890123" } }, "msg": "success", "tid": "747bbf80261844ed85b809212aab0d81"}