Create Transaction

Opens an eKYC transaction for a user and returns the JWT token the Mobile SDK authenticates with. This is the first call in an SDK-driven eKYC session.

Endpoint

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

{
  "user_id": "user_00000001",
  "ref_id": "ref_00000001",
  "level": 0
}

Parameters:

Param	Type	Required	Default	Description
user_id	string	Yes	—	The user ID.
ref_id	string	Yes	—	The transaction reference ID you generate and manage.
level	int	No	0	The challenge level. Higher levels require more stringent checks.

Headers:

Header	Required	Description
App-Id	No	The App-Id the transaction is scoped to. Defaults to default if omitted.

Returns: CreateTransactionResponse

Sample Request

curl --location '<BASE_URL>/v1/create_ekyc_transaction' \
  --header 'Authorization: ATV <ACCESS_ID>:<SIGNATURE>' \
  --header 'X-TV-Timestamp: <TIMESTAMP>' \
  --header 'App-Id: <APP_ID>' \
  --header 'Content-Type: application/json' \
  --data '{
    "user_id": "user_00000001",
    "ref_id": "ref_00000001",
    "level": 0
  }'

Response

{
  "success": true,
  "code": 0,
  "message": "Success",
  "request_id": "f48085e4-3ae4-40bb-b0e1-9b2c72575bc1",
  "data": {
    "id": "85712834-558f-4d9b-81bd-a2ab3b9a3aad",
    "ref_id": "ref_00000001",
    "user_id": "user_00000001",
    "status": "NOT_VERIFIED",
    "token": "<JWT_TOKEN>"
  }
}

Field	Type	Description
data.id	string	The transaction unique ID.
data.ref_id	string	The transaction reference ID you supplied.
data.user_id	string	The user ID.
data.status	string	NOT_VERIFIED, VERIFIED or EXPIRED.
data.token	string	The JWT token the Mobile SDK uses to authenticate with the server.
errors	array	Detail of each failure. Empty on success.
success	bool	Whether the call succeeded.
code	int	Numeric status code — 0 on success.

INFO

The response carries user_id, matching the request. Contact the CAKE team if you see document_id in its place.

WARNING

The token is scoped to one transaction and expires. Hand it to the SDK over your own authenticated channel and never log it — the Access Key must stay on your backend.

Errors

Code	Message
2001010	Access ID not found.
2001020	Transaction lock failed.
2001021	Invalid transaction request.
2002206	User profile is locked.
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_lock_failed	Transaction lock failed.
transaction_invalid_request	Invalid transaction request.
access_denied_exception	You are not authorized to perform the action.
user_profile_not_found_exception	The profile of user not found.
user_profile_locked	User profile has been locked.
internal_server_error	Some unexpected error occurs while processing the request.

Next Steps

• Upload Image — the next call once the SDK holds a token
• Get Transaction — poll the transaction status
• Verify Transaction Authentication Key — close the transaction