> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.idenfy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a Bank Card Session

> Create a standalone bank card verification session with the iDenfy API: expected name and last four, session URL, mobile code, session clocks, and redirect handling.

<Note>
  **Requirements:**

  * **API key pair** (API key + secret)
  * **Bank Card Verification** enabled on your account (contact iDenfy -- not self-service)
  * The **standalone** flow enabled on your account
  * **Finances** available for Bank Card Verification
</Note>

For how the card check works, what each verdict means, and how the dashboard side is configured, see the [Bank Card Verification](/guides/dashboard/features/bank-card-verification) guide. This documentation focuses on the API integration.

<Info>
  This page covers the **standalone** flow -- a card check that runs on its own token, with no identity verification behind it. To run the same check as an extra step inside a KYC session, set `bankCardVerification` when [generating an identity verification token](/kyc/generate-token) instead.
</Info>

## Create a Session

Authenticate with your **API key pair** -- API key as the username, API secret as the password, over HTTP Basic. Sessions are scoped to your partner account, so you only ever see your own.

<Info>
  For the full request and response schemas, every field's constraints and defaults, and an interactive playground, see the [**API Reference**](/api-reference/bank-card-verification/create-session) page for this endpoint.
</Info>

`expectedName` is the only required field -- the cardholder name read from the card is compared against it. Supplying `expectedLastFour` (exactly four digits) adds a second check against the card's actual last four digits. Creating a session pre-checks your finances; if they can't cover the check the request is rejected -- see [Errors](#errors).

### Example (Partner API)

<Tabs>
  <Tab title="Request">
    ```http theme={"system"}
    POST /bank-card/tokens/
    Authorization: Basic {API_KEY}:{API_SECRET}
    Content-Type: application/json

    {
      "expectedName": "Jane Doe",
      "expectedLastFour": "4242",
      "lifetime": 3600,
      "sessionLength": 30,
      "generateMobileCode": true,
      "successUrl": "https://partner.example.com/ok",
      "failUrl": "https://partner.example.com/denied"
    }
    ```
  </Tab>

  <Tab title="Response">
    ```json theme={"system"}
    {
      "tokenString": "b7c1…",
      "expiration": "2026-08-26T13:00:00Z",
      "isValid": true,
      "sessionUrl": "https://ui.idenfy.com/?bcvToken=b7c1…",
      "mobileCode": "48120537"
    }
    ```
  </Tab>
</Tabs>

***

## Sending the User to the Session

Redirect the end user to the returned `sessionUrl`, or embed it in an iFrame.

<Warning>
  **Embedding it yourself?** Your frame must grant camera access to the card capture origin, or card capture fails while document upload keeps working. See [Required Attributes](/kyc/iframe-redirect#required-attributes) for the `allow` attribute.
</Warning>

* **Mobile code.** When `generateMobileCode` is set, the response also carries an eight-digit `mobileCode`. Show it to the user so they can open the session in the iDenfy mobile app instead of following the link.
* **Desktop hand-off.** Desktop users are offered a QR code and an SMS link so they can finish on a phone camera. The desktop screen advances to the result on its own once the phone is done. Nothing is required from you.
* **Redirects.** `successUrl` and `failUrl` send the user back to your page once the check resolves. An **expired** session never redirects -- handle that case on your side, off the back of the webhook.

The flow is available in all [37 supported languages](/resources/supported-languages), switchable mid-flow.

***

## Session Lifetime

Two independent clocks govern a session.

| Clock             | Field           | Default | Range         | Starts                                           |
| ----------------- | --------------- | ------- | ------------- | ------------------------------------------------ |
| Link lifetime     | `lifetime`      | 1 hour  | up to 30 days | when the session is created                      |
| Capture countdown | `sessionLength` | --      | 1--60 minutes | at the capture step, not when the link is opened |

`lifetime` is set in **seconds**; `sessionLength` in **minutes**.

The end user gets three capture attempts by default, configurable per account. The counter is never shown to them, and a poor-quality capture does not spend an attempt on its own.

***

## Errors

| Status | Message                                                        | When                                                                                                |
| ------ | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `402`  | `"Action not allowed due to lack of funds or exceeded limit."` | Your finances cannot cover a bank card verification. Contact your account manager, or support team. |

***

## What's Next

Once the user finishes, the verdict is delivered to your endpoint. There is no Partner API endpoint for retrieving a standalone session, so configure a webhook if you need the result in your own systems -- see [Bank Card Webhooks](/bank-card/webhooks).


## Related topics

- [Create Verification Session](/kyc/generate-token.md)
- [Bank Card Verification Webhooks](/bank-card/webhooks.md)
- [Bank Card Verification](/guides/dashboard/features/bank-card-verification.md)
- [Request Update](/kyc/request-update.md)
- [Create session](/api-reference/bank-card-verification/create-session.md)