Tài liệu API thanh toán Việt Nam | ucake API Docs

API chi hộ

POST /vnpay/api/v1/payment

Gọi API này để chuyển tiền tới tài khoản ngân hàng của người dùng.

Trường yêu cầu

• amount - integer - Bắt buộc - Số tiền chi hộ. Khoảng tiền: 50,000 đến 50,000,000.
• orderNo - string - Bắt buộc - Mã đơn hàng merchant, phải duy nhất cho mỗi lần gọi.
• accountName - string - Bắt buộc - Tên người dùng
• phoneNo - string - Không bắt buộc - Số điện thoại người dùng
• accountNo - string - Bắt buộc - Số tài khoản người dùng
• accountType - integer - Bắt buộc - Loại tài khoản: 0 số tài khoản, 1 số thẻ.
• bankCode - string - Bắt buộc - Mã ngân hàng
• message - string - Bắt buộc - Ghi chú chi hộ
• returnURL - string - Bắt buộc - URL callback thông báo
• companyID - string - Bắt buộc - ID công ty do backend cấp.
• merchantID - string - Bắt buộc - ID merchant do backend cấp.
• timestamp - number - Bắt buộc - Dấu thời gian
• sign - string - Bắt buộc - Chữ ký

Trường phản hồi

• amount - integer - Số tiền giao dịch
• orderNo - string - Mã đơn hàng merchant được truyền vào.
• tradeNo - string - Mã giao dịch
• createTime - string - Thời gian tạo giao dịch. Định dạng: yyyy-MM-dd HH:mm:ss.
• updateTime - string - Thời gian cập nhật giao dịch cuối cùng.
• bankCode - string - Mã ngân hàng
• phoneNo - string - Số điện thoại
• accountName - string - Tên người dùng
• accountNo - string - Số tài khoản người dùng
• accountType - integer - Loại tài khoản
• message - String - Ghi chú

API tra cứu kết quả chi hộ

GET /vnpay/api/v1/paymentResult

Khi chi hộ đang xử lý, có thể chờ thông báo hoặc chủ động tra cứu.

Trường yêu cầu

• orderNo - string - Bắt buộc - Mã đơn hàng đã truyền vào API chi hộ.
• tradeNo - string - Bắt buộc - Mã giao dịch được API chi hộ trả về.
• companyID - string - Bắt buộc - ID công ty do backend cấp.
• merchantID - string - Bắt buộc - ID merchant do backend cấp.
• sign - string - Bắt buộc - Chữ ký
• timestamp - number - Bắt buộc - Dấu thời gian

Trường phản hồi

• amount - integer - Số tiền giao dịch
• orderNo - string - Mã đơn hàng merchant
• tradeNo - string - Mã giao dịch
• createTime - string - Thời gian tạo giao dịch
• updateTime - string - Thời gian cập nhật giao dịch cuối cùng.
• bankCode - string - Mã ngân hàng
• phoneNo - string - Số điện thoại
• accountName - string - Tên người dùng
• accountNo - string - Số tài khoản người dùng
• accountType - integer - Loại tài khoản
• message - string - Ghi chú

Tạo tài khoản ảo

POST /vnpay/api/v1/createVirtualCard

Tạo tài khoản ảo và trả về số tài khoản, chuỗi QRCode và liên kết ảnh VietQR.

Trường yêu cầu

• orderNo - string - Bắt buộc - Mã đơn giao dịch
• accountName - string - Không bắt buộc - Tên tài khoản ảo
• phoneNo - string - Không bắt buộc - Số điện thoại người dùng
• bankCode - string - Không bắt buộc - Ngân hàng dùng để tạo tài khoản ảo.
• companyID - string - Bắt buộc - ID công ty do backend cấp.
• merchantID - string - Bắt buộc - ID merchant do backend cấp.
• timestamp - string - Bắt buộc - Dấu thời gian
• sign - string - Bắt buộc - Chữ ký
• totalFee - Long - Không bắt buộc - Số tiền thu hộ

Trường phản hồi

• orderNo - string - Mã đơn giao dịch
• bankCode - string - Mã ngân hàng
• accountName - string - Tên tài khoản
• accountNo - string - Số tài khoản
• accountStatus - integer - Trạng thái: 0 đã đóng, 1 hoạt động.
• createdTime - string - Thời gian tạo
• expireTime - string - Thời gian hết hạn
• closeTime - string - Thời gian đóng
• QRCode - String - Dữ liệu chuỗi mã QR
• QRImgUrl - String - Liên kết ảnh VietQR

Đóng tài khoản ảo

POST /vnpay/api/v1/closeVirtualCard

Đóng tài khoản ảo chỉ định và trả về trạng thái sau khi đóng.

Trường yêu cầu

• accountNo - string - Không bắt buộc - Số tài khoản ngân hàng được trả về khi tạo.
• bankCode - string - Không bắt buộc - Mã ngân hàng
• companyID - string - Không bắt buộc - ID công ty do backend cấp.
• merchantID - string - Không bắt buộc - ID merchant do backend cấp.
• timestamp - integer - Không bắt buộc - Dấu thời gian
• sign - string - Không bắt buộc - Chữ ký

Trường phản hồi

• bankCode - string - Mã ngân hàng
• accountName - string - Tên tài khoản
• accountNo - string - Số tài khoản
• accountStatus - integer - Trạng thái: 0 đã đóng, 1 hoạt động.
• createdTime - string - Thời gian tạo
• expireTime - string - Thời gian hết hạn
• closeTime - string - Thời gian đóng

Tra cứu tài khoản ảo

GET /vnpay/api/v1/queryVirtualCard

Tra cứu trạng thái tài khoản ảo theo bankCode, accountName và accountNo.

Trường yêu cầu

• bankCode - string - Có - Mã ngân hàng
• accountName - string - Có - Tên tài khoản
• accountNo - string - Có - Số tài khoản
• companyID - string - Có - ID công ty do backend cấp.
• merchantID - string - Có - ID merchant do backend cấp.
• sign - string - Có - Chữ ký
• timestamp - string - Có - Dấu thời gian

Trường phản hồi

• bankCode - string - Mã ngân hàng
• accountName - string - Tên tài khoản
• accountNo - string - Số tài khoản
• accountStatus - integer - Trạng thái: 0 đã đóng, 1 hoạt động.
• createdTime - string - Thời gian tạo
• expireTime - string - Thời gian hết hạn
• closeTime - string - Thời gian đóng

Tra cứu số dư công ty

POST /vnpay/api/v1/queryBalance

Tra cứu số dư hiện tại của tài khoản công ty.

Trường yêu cầu

• companyID - string - Bắt buộc - ID công ty do backend cấp.
• merchantID - string - Bắt buộc - ID merchant do backend cấp.
• sign - string - Bắt buộc - Chữ ký
• timestamp - integer - Bắt buộc - Dấu thời gian

Trường phản hồi

• companyID - string - ID công ty do backend cấp.
• merchantID - string - ID merchant do backend cấp.
• balance - string - Số dư hiện tại của công ty

Tạo mã QR động

POST /vnpay/api/v1/createDynamicQr

Tạo mã QR động cho số tiền chỉ định và trả về chuỗi QR cùng thời gian hết hạn.

Trường yêu cầu

• merchantID - string - Bắt buộc - ID merchant do backend cấp.
• companyID - string - Bắt buộc - ID công ty do backend cấp.
• orderNo - string - Bắt buộc - Mã đơn giao dịch
• amount - Long - Bắt buộc - Số tiền thu hộ
• message - string - Không bắt buộc - Ghi chú
• timestamp - string - Bắt buộc - Dấu thời gian
• sign - string - Bắt buộc - Chữ ký

Trường phản hồi

• orderNo - string - Mã đơn giao dịch
• amount - Long - Số tiền thu hộ
• expiresAt - string - Thời gian hết hạn của mã QR động
• qrCode - String - Dữ liệu chuỗi mã QR

Thông báo kết quả chi hộ

URL đã truyền vào API chi hộ.

Khi chi hộ đang xử lý có kết quả cuối cùng, hệ thống sẽ gọi URL đã truyền vào API chi hộ để thông báo.

• companyID - string - ID công ty
• merchantID - string - ID merchant
• orderNo - string - Mã đơn hàng merchant
• tradeNo - string - Mã giao dịch
• bankCode - string - Mã ngân hàng
• accountNo - string - Số tài khoản
• amount - number - Số tiền giao dịch
• message - string - Ghi chú chi hộ
• result - String - Nguyên nhân khi giao dịch thất bại.
• updateTime - String - Thời gian cập nhật giao dịch
• status - number - Trạng thái giao dịch: 0 thành công, 3 thất bại, 4 đã hủy.
• sign - string - Chữ ký

Thông báo kết quả thu hộ

URL thông báo được cấu hình trong backend merchant.

Sau khi tài khoản ảo nhận tiền, thông tin thu hộ sẽ được gửi cho đối tác.

• companyID - string - ID công ty
• merchantID - string - ID merchant
• orderNo - string - Mã đơn hàng merchant
• tradeNo - string - Mã giao dịch
• bankCode - string - Mã ngân hàng
• accountNo - string - Số tài khoản ảo
• amount - number - Số tiền thu hộ
• message - string - Thông tin giao dịch do hệ thống thanh toán trả về.
• senderName - string - Người thanh toán
• senderAccount - string - Tài khoản thanh toán
• senderBankCode - string - Mã ngân hàng của người thanh toán
• sign - string - Chữ ký

Thông báo hoàn tiền

URL thông báo hoàn tiền được cấu hình trong backend merchant.

Sau khi hoàn tiền đơn hàng thành công, thông tin hoàn tiền sẽ được gửi cho đối tác.

• companyID - string - ID công ty
• merchantID - string - ID merchant
• orderNo - string - Mã đơn hàng merchant
• tradeNo - string - Mã giao dịch
• bankCode - string - Mã ngân hàng
• accountNo - string - Số tài khoản ngân hàng
• amount - number - Số tiền giao dịch
• updateTime - string - Thời gian cập nhật
• status - string - Trạng thái: 5 đã hoàn tiền.
• sign - string - Chữ ký