Skip to main content
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
For how the card check works, what each verdict means, and how the dashboard side is configured, see the Bank Card Verification guide. This documentation focuses on the API integration.
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 instead.

​
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.
For the full request and response schemas, every field’s constraints and defaults, and an interactive playground, see the API Reference page for this endpoint.
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.

​
Example (Partner API)

​
Sending the User to the Session

Redirect the end user to the returned sessionUrl, or embed it in an iFrame.
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 for the allow attribute.
  • 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, switchable mid-flow.

​
Session Lifetime

Two independent clocks govern a session. 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

​
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.

Related topics

Create Verification SessionBank Card Verification WebhooksRequest UpdateCreate sessionBank Card Verification