Create Transaction

Opens an NFC transaction and returns the JWT token the Mobile SDK uses to authenticate its chip read. This is the first call in every NFC session.

Endpoint

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

{
  "document_id": "001xxxxxxxxx",
  "ref_id": "ref_00000001"
}

Parameters:

Param	Type	Required	Default	Description
document_id	string	Yes	—	The Document ID — the citizen's NID number. Max length 64.
ref_id	string	Yes	—	The transaction reference ID you generate and manage. Max length 64.

Returns: CreateTransactionResponse

Authenticate this call with HMAC — see Overview § Authentication.

Sample Request

curl --location '<BASE_URL>/v1/create_transaction' \
  --header 'Authorization: ATV <ACCESS_ID>:<SIGNATURE>' \
  --header 'X-TV-Timestamp: <TIMESTAMP>' \
  --header 'Content-Type: application/json' \
  --data '{
    "document_id": "001xxxxxxxxx",
    "ref_id": "ref_00000001"
  }'

Response

{
  "success": true,
  "code": 0,
  "message": "success",
  "request_id": "133963a4-3d2c-4a85-b0a1-3fa2878b8f99",
  "data": {
    "id": "4b1f99a2-7569-4fde-b65a-1260794cb9c6",
    "ref_id": "ref_00000001",
    "document_id": "001xxxxxxxxx",
    "status": "NOT_VERIFIED",
    "token": "<JWT_TOKEN>"
  }
}

Field	Type	Description
code	int	The error code — 0 means no error. Max length 10.
request_id	string	The server request ID, used for tracing. Max length 64.
data.id	string	The transaction unique ID. Max length 64.
data.ref_id	string	The transaction reference ID you supplied. Max length 64.
data.document_id	string	The Document ID. Max length 64.
data.status	string	The transaction status: NOT_VERIFIED, VERIFIED or EXPIRED. Max length 32.
data.token	string	The per-transaction token the Mobile SDK uses to authenticate with the server. Max length 1000.

WARNING

The token is scoped to one transaction and expires. Pass it straight to the SDK over your own authenticated channel, never log it, and mint a new transaction rather than reusing an old token.

Errors

Code	Description
2001010	The API key is incorrect.
2001020	Transaction lock failed.
2001021	Invalid transaction request.
2001022	Transaction already verified.
2001023	Invalid transaction key.

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

Next Steps

• Read NFC — the SDK's next call, using the token returned here
• Overview — how the transaction status changes across the flow