Tạo giao dịch

Tạo một giao dịch và trả về khóa challenge (challenge key) dùng để tạo một OTP nâng cao (advance OTP). Server cũng push khóa challenge đến thiết bị của người dùng qua Firebase.

Endpoint

POST /api/v1/saas-sotp/create-transaction
Content-Type: application/json

{
  "partner_id": "{{partner_id}}",
  "partner_key": "{{partner_key}}",
  "token": "{{token}}",
  "app_id": "{{app_id}}",
  "transaction_id": "{{transaction_id}}",
  "transaction_desc": "{{transaction_desc}}",
  "transaction_amount": "{{transaction_amount}}",
  "transaction_date": "{{transaction_date}}",
  "receiver_account": "{{receiver_account}}",
  "sender_account": "{{sender_account}}",
  "currency": "VND",
  "type": "{{type}}",
  "transaction_metadata": "{\"test\":\"abc\"}"
}

Tham số:

Tham số	Kiểu	Bắt buộc	Mặc định	Mô tả
partner_id	string	Có	—	Partner ID.
partner_key	string	Có	—	Partner key.
token	string	Có	—	Token đăng ký được tạo bởi Đăng ký.
app_id	string	Có	—	Tên app dùng để tạo giao dịch.
transaction_id	string	Có	—	ID giao dịch duy nhất phía partner.
transaction_desc	string	Có	—	Mô tả giao dịch.
transaction_amount	string	Có	—	Số tiền giao dịch.
transaction_date	string	Có	—	Ngày giao dịch được tạo.
receiver_account	string	Có	—	ID tài khoản người nhận.
sender_account	string	Có	—	ID tài khoản người gửi.
currency	string	Có	—	Loại tiền tệ dùng để thực hiện giao dịch.
type	string	Có	—	Loại giao dịch, được định nghĩa phía partner.
transaction_metadata	string	Không	—	Thông tin giao dịch bổ sung, dưới dạng chuỗi JSON.

user_id và transaction_id tạo thành khóa tổng hợp (composite key) định danh giao dịch.

Trả về: CreateTransactionResponse

Ví dụ request

curl --location --request POST '<BASE_URL>/saas-sotp/create-transaction' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data-raw '{
    "partner_id": "{{partner_id}}",
    "partner_key": "{{partner_key}}",
    "token": "{{token}}",
    "app_id": "{{app_id}}",
    "transaction_id": "{{transaction_id}}",
    "transaction_desc": "{{transaction_desc}}",
    "transaction_amount": "{{transaction_amount}}",
    "transaction_date": "{{transaction_date}}",
    "receiver_account": "{{receiver_account}}",
    "sender_account": "{{sender_account}}",
    "currency": "VND",
    "type": "{{type}}",
    "transaction_metadata": "{\"test\":\"abc\"}"
  }'

Response

{
  "success": true,
  "code": 1,
  "message": "Success",
  "challenge_key": "fake_challenge_key"
}

Trường	Kiểu	Mô tả
success	bool	Trạng thái của request.
code	int	status code — 1 khi thành công.
message	string	Thông báo trạng thái hoặc lỗi.
challenge_key	string	Khóa challenge dùng để tạo OTP nâng cao.

challenge_key được trả về ở cấp cao nhất (top level), không nằm lồng trong data.

INFO

Khóa challenge được push đến thiết bị qua Firebase, đồng thời cũng được trả về ở đây. Chỉ trả nó về cho app trong response của riêng bạn khi push notification bị tắt cho người dùng đó — nếu không, hãy để push chuyển nó đi.

Lỗi

Mã	Mô tả
3	Parameter invalid
103	Thông tin Partner không chính xác — Partner details are incorrect.
126	Có lỗi xảy ra vui lòng thử lại — An error occurred, please retry.
129	Token không hợp lệ — Invalid token.
190108	Tài khoản chưa hoạt động — Account not activated.
190201	Không thể tạo transaction hoặc transaction_id đã tồn tại — Cannot create the transaction, or the id already exists.

190201 thường có nghĩa là transaction_id bị trùng. Hãy tạo một ID mới thay vì thử lại với cùng giá trị cũ.

Bước tiếp theo

• Xác minh OTP — xác minh OTP nâng cao được tạo từ khóa challenge này
• Lấy giao dịch — đọc lại khóa challenge nếu push bị lỡ