Get Card Enrollment Status

curl "https://sandbox.api.prava.space/v1/sessions/ses_123/status" \
  -H "Authorization: Bearer sk_test_..."

import requests

response = requests.get(
    "https://sandbox.api.prava.space/v1/sessions/ses_123/status",
    headers={"Authorization": "Bearer sk_test_..."},
)
enrollment = response.json()

const response = await fetch(
  `https://sandbox.api.prava.space/v1/sessions/${sessionId}/status`,
  {
    headers: {
      Authorization: `Bearer ${process.env.PRAVA_SECRET_KEY}`,
    },
  },
);

const enrollment = await response.json();

{
  "session_id": "ses_123",
  "status": "requires_action",
  "outcome": "not_started",
  "card_id": null,
  "passkey": null,
  "consent_status": "not_provided",
  "error": null
}

{
  "session_id": "ses_123",
  "status": "requires_action",
  "outcome": "card_provisioned",
  "card_id": "card_123",
  "passkey": null,
  "consent_status": "provided",
  "error": {
    "code": "DEVICE_BINDING_FAILED",
    "message": "Secure verification could not be completed. Try again.",
    "retryable": true
  }
}

{
  "session_id": "ses_123",
  "status": "completed",
  "outcome": "fully_enrolled",
  "card_id": "card_123",
  "passkey": "registered",
  "consent_status": "provided",
  "error": null
}

{
  "session_id": "ses_456",
  "status": "completed",
  "outcome": "fully_enrolled",
  "card_id": "card_456",
  "passkey": "existing",
  "consent_status": "not_provided",
  "error": null
}

{
  "session_id": "ses_789",
  "status": "failed",
  "outcome": "not_started",
  "card_id": null,
  "passkey": null,
  "consent_status": "not_provided",
  "error": {
    "code": "BIN_COUNTRY_NOT_ALLOWED",
    "message": "Card is not eligible",
    "retryable": false
  }
}

GET

sessions

{sessionId}

status

curl "https://sandbox.api.prava.space/v1/sessions/ses_123/status" \
  -H "Authorization: Bearer sk_test_..."

import requests

response = requests.get(
    "https://sandbox.api.prava.space/v1/sessions/ses_123/status",
    headers={"Authorization": "Bearer sk_test_..."},
)
enrollment = response.json()

const response = await fetch(
  `https://sandbox.api.prava.space/v1/sessions/${sessionId}/status`,
  {
    headers: {
      Authorization: `Bearer ${process.env.PRAVA_SECRET_KEY}`,
    },
  },
);

const enrollment = await response.json();

{
  "session_id": "ses_123",
  "status": "requires_action",
  "outcome": "not_started",
  "card_id": null,
  "passkey": null,
  "consent_status": "not_provided",
  "error": null
}

{
  "session_id": "ses_123",
  "status": "requires_action",
  "outcome": "card_provisioned",
  "card_id": "card_123",
  "passkey": null,
  "consent_status": "provided",
  "error": {
    "code": "DEVICE_BINDING_FAILED",
    "message": "Secure verification could not be completed. Try again.",
    "retryable": true
  }
}

{
  "session_id": "ses_123",
  "status": "completed",
  "outcome": "fully_enrolled",
  "card_id": "card_123",
  "passkey": "registered",
  "consent_status": "provided",
  "error": null
}

{
  "session_id": "ses_456",
  "status": "completed",
  "outcome": "fully_enrolled",
  "card_id": "card_456",
  "passkey": "existing",
  "consent_status": "not_provided",
  "error": null
}

{
  "session_id": "ses_789",
  "status": "failed",
  "outcome": "not_started",
  "card_id": null,
  "passkey": null,
  "consent_status": "not_provided",
  "error": {
    "code": "BIN_COUNTRY_NOT_ALLOWED",
    "message": "Card is not eligible",
    "retryable": false
  }
}

Poll the lifecycle of a full_enrollment session created by Enroll Card. This endpoint is server-to-server and returns no payment token, dynamic CVV, cryptogram, order, or transaction. GET /v1/sessions/{sessionId}/status · Authenticated with the same merchant secret key that created the session.

This endpoint supports only full_enrollment card sessions. Payment sessions must use Get Payment Result; calling the wrong status resource returns 409.

Path parameters

string

required

The session_id returned by POST /v1/sessions/enroll-card when enrollment_mode is full_enrollment.

Response

The JSON shape is stable across pending work, recoverable failures, success, cancellation, and expiry.

string

Enrollment session identifier.

string

Session lifecycle: requires_action, processing, completed, failed, cancelled, or expired.

string

Durable work completed: not_started, card_provisioned, or fully_enrolled.

string | null

Merchant-scoped card identifier. It becomes non-null after card provisioning succeeds, even if later passkey work is incomplete or fails.

string | null

registered when this flow created a passkey, existing when it verified an already available passkey, or null before passkey completion.

provided when the create request included consent_id; otherwise not_provided. This reports reference presence, not independent proof of consent.

object | null

Safe failure information: code, message, and retryable. It is null when no failure is active and after completion or cancellation.

How to interpret status and outcome

`status`	Typical `outcome`	Meaning	Integrator action
`requires_action`	`not_started`	The cardholder must continue in the iframe	Keep the iframe open and continue polling
`requires_action`	`card_provisioned`	The card is saved; passkey work still needs user action	Keep the same iframe and card
`processing`	`not_started` or `card_provisioned`	Prava or the card network is processing	Continue polling
`completed`	`fully_enrolled`	Card enrollment and passkey readiness are complete	Stop polling and store `card_id`
`failed`	`not_started` or `card_provisioned`	A non-recoverable step failed	Stop polling; inspect how much completed
`cancelled`	`not_started` or `card_provisioned`	The cardholder cancelled	Stop polling
`expired`	`not_started` or `card_provisioned`	The session expired before completion	Stop polling and create a new session if the user wants to continue

Enrollment success is exactly status: "completed" together with outcome: "fully_enrolled". Do not infer full enrollment from a non-null card_id: card_id proves only that card provisioning completed.

API compatibility note — upcoming webhook release

For an unfinished full-enrollment session, revocation at or after expires_at returns status: "expired". Earlier versions reported cancelled after any revocation. Revocation before expiry remains cancelled, including on repeated revoke calls after the deadline. Persisted completion and non-recoverable failure retain their existing precedence. The response fields and status enum are unchanged. Action required: If your integration treats every revoked session as cancelled, handle expired as a terminal result too. Stop polling in either case; create a new session only if the cardholder wants to continue. This matches the enrollment webhook event chronology.

Retry behavior

When error.retryable is true, the cardholder retries inside the existing iframe:

Do not call a retry API—there is no public retry endpoint.
Do not create another enrollment session.
Do not ask the cardholder to select or enter the card again after card_id exists.
Keep polling this same session_id while the cardholder selects Try again.

Prava retains the selected/provisioned card and restarts only the recoverable enrollment step. Incorrect OTP attempts remain inside the card-network experience and do not require merchant-side state.

Examples

curl "https://sandbox.api.prava.space/v1/sessions/ses_123/status" \
  -H "Authorization: Bearer sk_test_..."

import requests

response = requests.get(
    "https://sandbox.api.prava.space/v1/sessions/ses_123/status",
    headers={"Authorization": "Bearer sk_test_..."},
)
enrollment = response.json()

const response = await fetch(
  `https://sandbox.api.prava.space/v1/sessions/${sessionId}/status`,
  {
    headers: {
      Authorization: `Bearer ${process.env.PRAVA_SECRET_KEY}`,
    },
  },
);

const enrollment = await response.json();

{
  "session_id": "ses_123",
  "status": "requires_action",
  "outcome": "not_started",
  "card_id": null,
  "passkey": null,
  "consent_status": "not_provided",
  "error": null
}

{
  "session_id": "ses_123",
  "status": "requires_action",
  "outcome": "card_provisioned",
  "card_id": "card_123",
  "passkey": null,
  "consent_status": "provided",
  "error": {
    "code": "DEVICE_BINDING_FAILED",
    "message": "Secure verification could not be completed. Try again.",
    "retryable": true
  }
}

{
  "session_id": "ses_123",
  "status": "completed",
  "outcome": "fully_enrolled",
  "card_id": "card_123",
  "passkey": "registered",
  "consent_status": "provided",
  "error": null
}

{
  "session_id": "ses_456",
  "status": "completed",
  "outcome": "fully_enrolled",
  "card_id": "card_456",
  "passkey": "existing",
  "consent_status": "not_provided",
  "error": null
}

{
  "session_id": "ses_789",
  "status": "failed",
  "outcome": "not_started",
  "card_id": null,
  "passkey": null,
  "consent_status": "not_provided",
  "error": {
    "code": "BIN_COUNTRY_NOT_ALLOWED",
    "message": "Card is not eligible",
    "retryable": false
  }
}

Polling example

Poll from your backend, not the browser. A practical starting cadence is once per second while the cardholder is active, backing off toward five seconds during longer processing. The endpoint is limited to 120 requests per minute.

const terminal = new Set(['completed', 'failed', 'cancelled', 'expired']);

async function waitForEnrollment(sessionId: string) {
  let delayMs = 1_000;

  while (true) {
    const response = await fetch(
      `https://sandbox.api.prava.space/v1/sessions/${sessionId}/status`,
      {
        headers: {
          Authorization: `Bearer ${process.env.PRAVA_SECRET_KEY}`,
        },
      },
    );

    if (!response.ok) throw new Error(`Status request failed: ${response.status}`);

    const result = await response.json();
    if (terminal.has(result.status)) return result;

    await new Promise((resolve) => setTimeout(resolve, delayMs));
    delayMs = Math.min(delayMs * 1.5, 5_000);
  }
}

Error responses

Enrollment lifecycle failures use HTTP 200 with the stable response above. HTTP errors mean the status request itself could not be served.

Status	Code	Cause	Recovery
401	`AUTH_1001` / `AUTH_1002`	Missing or invalid secret key	Use the key that created the session
404	`NOT_FOUND`	Session not found or owned by another merchant	Verify the session and environment
409	`SESSION_STATUS_UNSUPPORTED`	The session is a payment or another unsupported flow	Use that flow’s result endpoint
409	`ENROLLMENT_ACTION_NOT_FOUND`	Enrollment action is not linked correctly	Contact support with the `X-Response-ID`
429	Rate limited	Polling exceeded the endpoint limit	Back off before retrying

Every response includes an X-Response-ID header. Include it when contacting support@prava.space.

Authorizations

Authorization

string

header

required

Your secret key: sk_test_* (sandbox) or sk_live_* (production).

Path Parameters

sessionId

string

required

The session_id returned for a full_enrollment request

Response

Current card-enrollment lifecycle

session_id

string

required

status

enum<string>

required

Lifecycle state of the interactive session.

Available options:

requires_action,

processing,

completed,

failed,

cancelled,

expired

outcome

enum<string>

required

The durable enrollment work that has completed.

Available options:

not_started,

card_provisioned,

fully_enrolled

card_id

string | null

required

Merchant-scoped card identifier after provisioning.

passkey

enum<string> | null

required

Whether this flow registered a passkey, verified an existing one, or has not completed passkey readiness.

Available options:

registered,

existing,

null

Whether consent_id was supplied on session creation.

Available options:

provided,

not_provided

error

null | object

required

Show child attributes

Server-Side API

Reference

Path parameters

Response

How to interpret status and outcome

API compatibility note — upcoming webhook release

Retry behavior

Examples

Polling example

Error responses

Authorizations

Path Parameters

Response

​Path parameters

​Response

​How to interpret status and outcome

​API compatibility note — upcoming webhook release

​Retry behavior

​Examples

​Polling example

​Error responses

Authorizations

Path Parameters

Response

Path parameters

Response

How to interpret status and outcome

API compatibility note — upcoming webhook release

Retry behavior

Examples

Polling example

Error responses