Platform API · API Docs · eKYC Platform

Initialize

POST/ekyc/platform/init

Initializes an eKYC session from the client-generated encrypted token, and returns the session token, an access token and the bootstrap configuration.

Request

MethodPOST
Path/ekyc/platform/init
Content-Typeapplication/json
Auth requiredNo

This single call handles token parsing, application creation (or lookup), bootstrap configuration, and access token issuance.

Authentication

This is the call that issues the access_token the other endpoints pass as a Bearer token, so it takes no Authorization header of its own — it authenticates with the encrypted_token in the body. See Authentication Mechanism.

NameTypeRequiredDescription
encrypted_tokenstringRequiredThe ENCODED_VALUE generated by the Authentication mechanism (AES-256 CBC encrypted user identity, Base64 URL encoded with key ID prefix)
flow_idstringOptionalSpecific flow to initialize
card_typesstringOptionalComma-separated list of allowed card types (e.g. vn.national_id,vn.passport)
langstringOptionalLanguage code (e.g. vi, en)
metadataobjectOptionalOptional prepared metadata (e.g. applicant identity PII), already encrypted by you. JSON ≤ 8 KB. Persisted onto the application's client_metadata on first init only — repeat calls for the same user ignore this field.

All parameters go in the JSON body; the endpoint does not read query parameters.

Idempotency: the user reference inside encrypted_token is the idempotency key. The first call creates the application; later calls with the same token return the same token and a freshly signed access_token.

Sample request

JSON
{
  "encrypted_token": "<ENCODED_VALUE>",
  "flow_id": "<flow_id>",
  "card_types": "vn.national_id,vn.passport",
  "lang": "vi",
  "metadata": { "applicant_name": "<already-encrypted>" }
}

Response

An HTTP 200 with the top-level verdict set to success means the session initialized. data.access_token is the JWT to pass as a Bearer token on the calls that follow, data.token is the session's unique token, and data.bootstrap is the bootstrap configuration this call resolved.

JSON
{
  "data": {
    "token": "<unique_token>",
    "access_token": "<JWT>",
    "bootstrap": {
      "lender_code": "lender_vn",
      "lender_country": "VN",
      "lender_language": "vi",
      "ui_version": "4.0",
      "masked_phone_number": "09*****123",
      "required_steps": [],
      "flow_selected_at": 1700000000,
      "lead_source": "sms",
      "client_custom_settings": {}
    }
  },
  "message": "platform init successfully",
  "time": "2026-01-01T00:00:00Z",
  "verdict": "success"
}

Failure codes

The top-level verdict names the outcome, alongside the HTTP status code:

verdictStatus codeDescription
success200Session initialized successfully.
missing_parameters400encrypted_token is missing from the body.
invalid_parameters400encrypted_token is undecodable, or metadata exceeds 8 KB.
malformed_json400Request body is not valid JSON.
record_not_found404Encryption key, lender, or application not found / inactive / expired.
invalid_method405Wrong HTTP verb — this endpoint accepts POST only.
limit_exceeded429Concurrent init request in progress for the same token — retry shortly.
failure500Internal server error.