Thanh toán / Giải ngân đến tài khoản ngân hàng

Thực hiện chuyển khoản từ tài khoản VA của partner đến tài khoản ngân hàng người nhận. Giao dịch được tạo với trạng thái PENDING và hệ thống sẽ xử lý bất đồng bộ.

Cách tạo key

Tạo một UUID v4 ngẫu nhiên trước khi gửi request.

Mỗi giao dịch mới phải dùng một UUID khác nhau.

Key có hiệu lực trong 30 phút kể từ lần gửi đầu tiên.

Quy tắc sử dụng

Tình huống	Hành vi hệ thống
Key mới, chưa tồn tại	Tiếp nhận và xử lý giao dịch bình thường
Key đã tồn tại (retry với cùng key)	Trả về 409 Conflict — giao dịch đã được tiếp nhận trước đó
Thiếu header `Idempotency-Key`	Trả về 400 Bad Request
Key sai định dạng (không phải UUID v4)	Trả về 400 Bad Request
Key hết hạn (sau 30 phút)	Hệ thống coi như key mới, có thể gửi lại

Ví dụ sử dụng

Lưu ý quan trọng

KHÔNG tái sử dụng key của giao dịch trước cho một giao dịch mới.

Nếu nhận được 409, kiểm tra trạng thái giao dịch qua GET /partner/vnvn/transactions bằng transactionCode hoặc id đã nhận trước đó.

Nếu không chắc giao dịch đã được xử lý chưa (do timeout), hãy dùng cùng key cũ để retry — nếu trả về 409 nghĩa là giao dịch đã được tiếp nhận.

Giới hạn khác:

Số tiền tối thiểu: 50.000 VND

Số tiền tối đa: 299.999.999 VND/giao dịch

Nội dung chuyển khoản tối đa 155 ký tự, chỉ chấp nhận chữ không dấu và số

Xác thực qua x-api-key, không cần PIN hay sinh trắc học

application/json

Yêu cầu thanh toán được tạo thành công. Kiểm tra trạng thái thực tế qua GET /partner/vnvn/transactions/{id}.

Bodyapplication/json

curl --location 'https://api.itax.dev/partner/vnvn/va-transfer' \ --header 'Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000' \ --header 'x-api-key: <api-key>' \ --header 'Content-Type: application/json' \ --data '{ "amount": 100000, "bankId": "TPB", "bankCode": "970423", "bankRefNumber": "dohoangtien", "bankRefName": "DO HOANG TIEN", "content": "Thanh toan don hang 001" }'

{ "statusCode": 200, "message": "Transfer request created successfully", "data": { "success": true, "message": "Yêu cầu chuyển khoản đã được tạo thành công và đang được xử lý", "transactionCode": "ITAX_TXN_user123_TRANSFER_OUT_1747030000000", "transactionId": "cm4abcd1234", "status": "PENDING" } }

Thanh toán / Giải ngân đến tài khoản ngân hàng

Cách tạo key#

Quy tắc sử dụng#

Ví dụ sử dụng#

Lưu ý quan trọng#

Request

Responses

Cách tạo key

Quy tắc sử dụng

Ví dụ sử dụng

Lưu ý quan trọng