Create Transaction

Creates a transaction and returns the challenge key used to generate an advance OTP. The server also pushes the challenge key to the user's device via 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\"}"
}

Parameters:

Param	Type	Required	Default	Description
partner_id	string	Yes	—	The partner id.
partner_key	string	Yes	—	The partner key.
token	string	Yes	—	The registration token generated by Register.
app_id	string	Yes	—	The app name the transaction was created under.
transaction_id	string	Yes	—	The unique transaction id on the partner side.
transaction_desc	string	Yes	—	The transaction description.
transaction_amount	string	Yes	—	The transaction amount.
transaction_date	string	Yes	—	The date the transaction was created.
receiver_account	string	Yes	—	The receiver account id.
sender_account	string	Yes	—	The sender account id.
currency	string	Yes	—	The currency used to perform the transaction.
type	string	Yes	—	The type of transaction, defined on the partner side.
transaction_metadata	string	No	—	Additional transaction information, as a JSON string.

user_id and transaction_id form the composite key identifying the transaction.

Returns: CreateTransactionResponse

Sample 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"
}

Field	Type	Description
success	bool	Request status.
code	int	The status code — 1 on success.
message	string	The status or error message.
challenge_key	string	The challenge key used to generate the advance OTP.

challenge_key is returned at the top level, not nested under data.

INFO

The challenge key is pushed to the device via Firebase as well as returned here. Return it to the app in your own response only when push notifications are switched off for that user — otherwise let the push deliver it.

Errors

Code	Description
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 most often means a duplicate transaction_id. Generate a fresh one rather than retrying with the same value.

Next Steps

• Validate OTP — verify the advance OTP generated from this challenge key
• Get Transaction — re-read the challenge key if the push was missed