Verify Transaction Authentication Key

Redeems the authentication key produced by a product's verification step and moves the transaction to VERIFIED. This is the step that turns a face match or chip read into a transaction your backend can trust.

Endpoint

POST /v1/verify_transaction_key
Content-Type: application/json

{
  "user_id": "user_00000001",
  "ref_id": "ref_00000001",
  "authentication_key": "<AUTHENTICATION_KEY>"
}

Parameters:

Param	Type	Required	Default	Description
user_id	string	Yes	—	The user ID.
ref_id	string	Yes	—	The transaction reference ID.
authentication_key	string	Yes	—	The authentication key generated by the product verification step that preceded this call.

Returns: VerifyTransactionKeyResponse

Sample Request

curl --location '<BASE_URL>/v1/verify_transaction_key' \
  --header 'Authorization: ATV <ACCESS_ID>:<SIGNATURE>' \
  --header 'X-TV-Timestamp: <TIMESTAMP>' \
  --header 'Content-Type: application/json' \
  --data '{
    "user_id": "user_00000001",
    "ref_id": "ref_00000001",
    "authentication_key": "<AUTHENTICATION_KEY>"
  }'

Response

{
  "data": {
    "id": "69306e8a-68e3-43f6-97ae-02b8e7c356f7",
    "ref_id": "ref_00000001",
    "user_id": "user_00000001",
    "status": "VERIFIED"
  },
  "errors": []
}

Field	Type	Description
data.id	string	The transaction unique ID.
data.ref_id	string	The transaction reference ID.
data.user_id	string	The user ID.
data.status	string	VERIFIED on success.
errors	array	Detail of each failure. Empty on success.

WARNING

Redeem the key from your backend, never from the app. The authentication key is the single artefact that proves the user passed the biometric check — call this endpoint server-to-server only.

Errors

Code	Message
2001010	Access ID not found.
2001020	Transaction lock failed.
2001021	Invalid transaction request.
2001023	Invalid transaction key.
401100	You are not authorized to perform the action.
4001000	Input parameter violates a constraint.
4001001	The X-TV-Timestamp header is expired, need a newer one.
5001000	Some unexpected error occurs while processing the request.

Code	Description
access_id_not_found	The API key is incorrect.
transaction_invalid_request	Invalid transaction request.
internal_server_error	Some unexpected error occurs while processing the request.

Code	Error code	Description
401	access_denied_exception	You are not authorized to perform the action.
500	internal_server_error	Some unexpected error occurs while processing the request.

Next Steps

• Get Transaction — confirm the status afterwards
• Create Transaction — where the transaction was opened