Get transaction

GET /api/account/integration/kyc/transaction/{transaction_id}

Returns the transaction: where it is in its lifecycle and, once analysis has finished, the decision with every reason behind it.

Request

string

required

Bearer {access_token} — see Authentication.

string (UUID)

required

The id returned by Create transaction.

Response

string (UUID)

The transaction id.

string (UUID)

The customer this transaction belongs to.

string

CREATED, INITIATED, COMPLETED, PROCESSING, FINISHED, FAILED or EXPIRED. See How verification works.

string (ISO-8601)

When your backend opened the transaction.

string (ISO-8601) | null

When the SDK started the session on the device.

string (ISO-8601) | null

When the user finished capture.

string (ISO-8601) | null

When analysis started.

string (ISO-8601) | null

When analysis ended.

object | null

The analysis result. null until the transaction reaches FINISHED or FAILED. Full structure in Reading a result.

Example

curl https://{your-api-host}/api/account/integration/kyc/transaction/34dc4204-2b57-42ae-a3bc-1d114935b98f \
  -H "Authorization: Bearer $ACCESS_TOKEN"

const res = await fetch(
  `${CHMOD_API_URL}/api/account/integration/kyc/transaction/${transactionId}`,
  { headers: { Authorization: `Bearer ${accessToken}` } },
);

const transaction = await res.json();

if (transaction.status === "FINISHED") {
  handleDecision(transaction.result_data.decision, transaction.result_data.issues);
}

res = requests.get(
    f"{CHMOD_API_URL}/api/account/integration/kyc/transaction/{transaction_id}",
    headers={"Authorization": f"Bearer {access_token}"},
)
transaction = res.json()

Response — approved

{
  "id": "34dc4204-2b57-42ae-a3bc-1d114935b98f",
  "customer_id": "4a63b11c-803d-4126-bf91-d5f8290ff0a5",
  "created_at": "2026-09-10T14:22:00.000Z",
  "initiated_at": "2026-09-10T14:23:12.450Z",
  "completed_at": "2026-09-10T14:25:30.110Z",
  "processing_at": "2026-09-10T14:25:30.980Z",
  "finished_at": "2026-09-10T14:25:44.220Z",
  "status": "FINISHED",
  "result_data": {
    "decision": "APPROVED",
    "issues": [],
    "document": { "status": "PASSED", "data": { "...": "..." } },
    "liveness": { "status": "PASSED", "data": { "...": "..." } },
    "face_comparison": { "status": "PASSED", "data": { "...": "..." } }
  }
}

Response — rejected

{
  "id": "34dc4204-2b57-42ae-a3bc-1d114935b98f",
  "customer_id": "4a63b11c-803d-4126-bf91-d5f8290ff0a5",
  "status": "FINISHED",
  "result_data": {
    "decision": "REJECTED",
    "issues": [
      {
        "type": "REJECT",
        "code": "EXPIRED_DOCUMENT",
        "message": "The document has expired.",
        "details": { "evaluated_at": "2026-09-10" }
      },
      {
        "type": "REJECT",
        "code": "SURNAME_MISMATCH",
        "message": "The surnames on the document do not match the expected value.",
        "details": { "score": 0.41, "threshold": 0.85 }
      }
    ],
    "document": { "status": "REJECTED", "data": { "...": "..." } },
    "liveness": { "status": "PASSED", "data": { "...": "..." } }
  }
}

Response — still in progress

{
  "id": "34dc4204-2b57-42ae-a3bc-1d114935b98f",
  "customer_id": "4a63b11c-803d-4126-bf91-d5f8290ff0a5",
  "created_at": "2026-09-10T14:22:00.000Z",
  "initiated_at": "2026-09-10T14:23:12.450Z",
  "status": "INITIATED",
  "result_data": null
}

Polling

Prefer webhooks: they arrive as soon as the decision exists, and polling a transaction that is still INITIATED tells you nothing you did not already know. When you do poll — as a reconciliation job, or as a fallback when a webhook did not arrive — back off rather than hammering:

async function waitForDecision(transactionId: string, timeoutMs = 120_000) {
  const deadline = Date.now() + timeoutMs;
  let delay = 2_000;

  while (Date.now() < deadline) {
    const tx = await getTransaction(transactionId);

    // FINISHED and FAILED are terminal; EXPIRED means the user never came back.
    if (["FINISHED", "FAILED", "EXPIRED"].includes(tx.status)) return tx;

    await sleep(delay);
    delay = Math.min(delay * 2, 15_000);
  }

  throw new Error(`Transaction ${transactionId} did not settle in time`);
}

Analysis normally settles within seconds of the user finishing. A transaction sitting in INITIATED is waiting on the user, not on chmod — it will move to EXPIRED once transaction_ttl_minutes elapses.

Reading a result

Every field inside result_data.

Issue codes

What each rejection reason means.

Getting Started

Customers

Transactions

Transaction configuration

Results

Get transaction

Request

Response

Example

Polling

Next

Reading a result

Issue codes

​Request

​Response

​Example

​Polling

​Next

Reading a result

Issue codes

Request

Response

Example

Polling

Next