Vietnam Payment API Documentation | ucake API Docs

Payout API

POST /vnpay/api/v1/payment

Use this API to send funds to a user bank account.

Required fields

• amount - integer - Required - Payout amount. Range: 50,000 to 50,000,000.
• orderNo - string - Required - Merchant order number. Must be unique for each request.
• accountName - string - Required - User name
• phoneNo - string - Optional - User phone number
• accountNo - string - Required - User account number
• accountType - integer - Required - Account type: 0 account number, 1 card number.
• bankCode - string - Required - Bank code
• message - string - Required - Payout note
• returnURL - string - Required - Callback notification URL
• companyID - string - Required - Company ID assigned by the backend.
• merchantID - string - Required - Merchant ID assigned by the backend.
• timestamp - number - Required - Timestamp
• sign - string - Required - Signature

Response fields

• amount - integer - Transaction amount
• orderNo - string - Merchant order number from the request.
• tradeNo - string - Transaction serial number
• createTime - string - Transaction creation time. Format: yyyy-MM-dd HH:mm:ss.
• updateTime - string - Last transaction update time.
• bankCode - string - Bank code
• phoneNo - string - Phone number
• accountName - string - User name
• accountNo - string - User account number
• accountType - integer - Account type
• message - String - Note

Payout result query API

GET /vnpay/api/v1/paymentResult

When a payout is processing, wait for notification or query the result manually.

Required fields

• orderNo - string - Required - Order number submitted to the payout API.
• tradeNo - string - Required - Transaction serial number returned by the payout API.
• companyID - string - Required - Company ID assigned by the backend.
• merchantID - string - Required - Merchant ID assigned by the backend.
• sign - string - Required - Signature
• timestamp - number - Required - Timestamp

Response fields

• amount - integer - Transaction amount
• orderNo - string - Merchant order number
• tradeNo - string - Transaction serial number
• createTime - string - Transaction creation time
• updateTime - string - Last transaction update time.
• bankCode - string - Bank code
• phoneNo - string - Phone number
• accountName - string - User name
• accountNo - string - User account number
• accountType - integer - Account type
• message - string - Note

Create virtual account

POST /vnpay/api/v1/createVirtualCard

Create a virtual account and return account number, QRCode string and VietQR image URL.

Required fields

• orderNo - string - Required - Transaction order number
• accountName - string - Optional - Virtual account name
• phoneNo - string - Optional - User phone number
• bankCode - string - Optional - Bank used to apply for the virtual account.
• companyID - string - Required - Company ID assigned by the backend.
• merchantID - string - Required - Merchant ID assigned by the backend.
• timestamp - string - Required - Timestamp
• sign - string - Required - Signature
• totalFee - Long - Optional - Collection amount

Response fields

• orderNo - string - Transaction order number
• bankCode - string - Bank code
• accountName - string - Account name
• accountNo - string - Account number
• accountStatus - integer - Status: 0 closed, 1 active.
• createdTime - string - Created time
• expireTime - string - Expiration time
• closeTime - string - Close time
• QRCode - String - QR code string data
• QRImgUrl - String - VietQR image URL

Close virtual account

POST /vnpay/api/v1/closeVirtualCard

Close the specified virtual account and return its status after closing.

Required fields

• accountNo - string - Optional - Bank account number returned when created.
• bankCode - string - Optional - Bank code
• companyID - string - Optional - Company ID assigned by the backend.
• merchantID - string - Optional - Merchant ID assigned by the backend.
• timestamp - integer - Optional - Timestamp
• sign - string - Optional - Signature

Response fields

• bankCode - string - Bank code
• accountName - string - Account name
• accountNo - string - Account number
• accountStatus - integer - Status: 0 closed, 1 active.
• createdTime - string - Created time
• expireTime - string - Expiration time
• closeTime - string - Close time

Query virtual account

GET /vnpay/api/v1/queryVirtualCard

Query virtual account status by bankCode, accountName and accountNo.

Required fields

• bankCode - string - Yes - Bank code
• accountName - string - Yes - Account name
• accountNo - string - Yes - Account number
• companyID - string - Yes - Company ID assigned by the backend.
• merchantID - string - Yes - Merchant ID assigned by the backend.
• sign - string - Yes - Signature
• timestamp - string - Yes - Timestamp

Response fields

• bankCode - string - Bank code
• accountName - string - Account name
• accountNo - string - Account number
• accountStatus - integer - Status: 0 closed, 1 active.
• createdTime - string - Created time
• expireTime - string - Expiration time
• closeTime - string - Close time

Query company balance

POST /vnpay/api/v1/queryBalance

Query the current company account balance.

Required fields

• companyID - string - Required - Company ID assigned by the backend.
• merchantID - string - Required - Merchant ID assigned by the backend.
• sign - string - Required - Signature
• timestamp - integer - Required - Timestamp

Response fields

• companyID - string - Company ID assigned by the backend.
• merchantID - string - Merchant ID assigned by the backend.
• balance - string - Current company balance

Create dynamic QR

POST /vnpay/api/v1/createDynamicQr

Create a dynamic QR for a specified amount and return the QR string and expiration time.

Required fields

• merchantID - string - Required - Merchant ID assigned by the backend.
• companyID - string - Required - Company ID assigned by the backend.
• orderNo - string - Required - Transaction order number
• amount - Long - Required - Collection amount
• message - string - Optional - Note
• timestamp - string - Required - Timestamp
• sign - string - Required - Signature

Response fields

• orderNo - string - Transaction order number
• amount - Long - Collection amount
• expiresAt - string - Dynamic QR expiration time
• qrCode - String - QR code string data

Payout result notification

URL submitted in the payout API.

When a processing payout has a final result, the URL submitted to the payout API is called for notification.

• companyID - string - Company ID
• merchantID - string - Merchant ID
• orderNo - string - Merchant order number
• tradeNo - string - Transaction serial number
• bankCode - string - Bank code
• accountNo - string - Account number
• amount - number - Transaction amount
• message - string - Payout note
• result - String - Failure reason when the transaction fails.
• updateTime - String - Transaction update time
• status - number - Transaction status: 0 success, 3 failed, 4 canceled.
• sign - string - Signature

Collection result notification

Notification URL configured in the merchant backend.

After a virtual account receives funds, collection information is sent to the partner.

• companyID - string - Company ID
• merchantID - string - Merchant ID
• orderNo - string - Merchant order number
• tradeNo - string - Transaction serial number
• bankCode - string - Bank code
• accountNo - string - Virtual account number
• amount - number - Collection amount
• message - string - Transaction message returned by the payment system.
• senderName - string - Payer
• senderAccount - string - Payer account
• senderBankCode - string - Payer bank code
• sign - string - Signature

Refund notification

Refund notification URL configured in the merchant backend.

After an order refund succeeds, refund information is sent to the partner.

• companyID - string - Company ID
• merchantID - string - Merchant ID
• orderNo - string - Merchant order number
• tradeNo - string - Transaction serial number
• bankCode - string - Bank code
• accountNo - string - Bank account number
• amount - number - Transaction amount
• updateTime - string - Update time
• status - string - Status: 5 refunded.
• sign - string - Signature