Bank Card Recognition API

Authentication

You need to add a token header with the value received from an x-faces representative.

Response Wrapper Format

All responses from X-Faces follow this format:

{
  "result": "bool",
  "message": "string"
}

result: whether the recognition of the bank card was launched successfully
message: optional message accompanying the result

Recognize Card

Endpoint: POST https://api.x-faces.xyz/v1/card/recognize

Data Structure

{
  "user_external_id": "string",
  "expected_number": "string (optional)",
  "name": "string (optional)",
  "callback_url": "string",
  "image": "string base64" | ["string base64", "..."]
}

user_external_id: user identifier in the external system
expected_number: (Optional) expected bank card number. Digits can be replaced with a wildcard, e.g. 1111 **** 2222 3333; any non-digit character can be used as a wildcard. Spaces and hyphens are ignored.
name: (Optional) full cardholder name supplied by the partner. It is used to verify the recognized cardholder according to the source priority described below. The name parts may be supplied in any order.
callback_url: URL to where we should send the callback of image recognition
image: bank card image to be processed as base64 string, or a list of base64 strings

Cardholder Name Verification

X-Faces can compare the recognized cardholder with either the verified identity document stored in X-Faces or the partner-provided name.

User state	Partner supplied `name`	Name source used for comparison
Verified user	Yes or no	Identity document name; if unavailable, partner-provided `name`
Unverified user	Yes	Partner-provided `name`
Unverified user	No	Identity document name, if available
Any user	Neither source is available	Name comparison is not performed

Names are normalized before comparison: case, diacritics, dots, hyphens, surrounding whitespace, and word order are handled. Matching uses fuzzy comparison with names in any order.

When the partner-provided name is used, expected_name contains the comparison result. verified receives the same result unless another validation, such as an expected_number mismatch, makes the document unverified. If no usable name source or recognized cardholder is available, name comparison does not produce a verification decision.

Possible `result` and `message` Combinations

Below are the possible values returned by the API in the result and message fields of the response:

✅ When `result: true`

The payload was successfully passed to the model for recognition.

❌ When `result: false`

An error occurred while passing the payload to the model for recognition.

Message	Description
`Invalid token`	The authentication token passed in the headers is incorrect.
`No payload sent`	The request body was empty.
`No image provided in the payload`	Endpoint received the payload with the empty `image` key.
`Invalid image format: {exception message}`	Passed image can not be converted to RGB / formatted as JPEG / represented as base64 string.
`Failed to create user`	An unexpected error occurred while creating a user.
`Failed to create a challenge`	An unexpected error occurred while creating a challenge.

Example request and response

Example with Postman

Bank card recognition request and response

Fetching Result of Image Recognition

Once the bank card image is processed, X-Faces will send a callback to your specified callback_url.
The payload of this callback will look like:

{
  "created_at": "2025-04-07T12:18:00.881465+00:00",
  "updated_at": "2025-04-07T12:18:08.814901",
  "u_uuid": "0532becb-8232-4082-baab-04e30997dd52",
  "external_id": "ft43w342s2",
  "verified": false,
  "verified_at": null,
  "challenge_id": "7267abad-5a5b-4a6b-b391-b8eff2cc9601",
  "multiaccounts": null,
  "changed": [
    "bankcard_capture"
  ]
}

Using challenge_id, the challenge itself can be retrieved through endpoint:

Endpoint: GET https://api.x-faces.xyz/v1/card/get/<challenge_id>

Replace challenge_id with the value from the callback.

Example Response:

{
  "data": {
    "c_uuid": "7267abad-5a5b-4a6b-b391-b8eff2cc9601",
    "created_at": "2025-04-07T12:18:00.881465+00:00",
    "data": [
      {
        "data": [
          {
            "timestamp": 174402828089
          }
        ],
        "id": 3,
        "status": "completed",
        "type": "bankcard_capture"
      }
    ],
    "images": {
      "bank_card": [
        "752aa8ce-22ee-459d-993c-858ee70cf6d3"
      ]
    },
    "ip": "...",
    "is_multiaccount": false,
    "project_id": {
      "name": "...",
      "p_uuid": "..."
    },
    "result": {
      "bank_card": {
        "bank": "Revolut",
        "capture_mode": "screenshot",
        "card_layout": "",
        "card_type": "virtual_card",
        "cardholder": "FLORIN-ADRIAN CIOCAN",
        "code_is_valid": true,
        "d_uuid": "eb4c76e0-6243-4626-873a-69bf9cde513e",
        "document_type": "rou_bcard",
        "exp": "08/28",
        "expected_name": true,
        "fraud": false,
        "hide_numbers": false,
        "identity": "rou_bcard-eb4c76e0-6243-4626-873a-69bf9cde513e",
        "is_apple_pay": false,
        "is_expired": false,
        "is_front_side": true,
        "is_physical_card": false,
        "is_valid": true,
        "is_vertical": false,
        "num": "425011********9303",
        "physically_damaged": false,
        "system": "VISA",
        "type": 110,
        "verified": true
      },
      "end_work": "2025-04-07T12:18:08.315876",
      "start_work": "2025-04-07T12:18:01.188262"
    },
    "status": "posted",
    "type": null,
    "updated_at": "2025-04-07T12:18:08.896588",
    "user_id": "0532becb-8232-4082-baab-04e30997dd52"
  },
  "result": true
}

Response Fields

Common Fields

Field	Type	Description
`capture_mode`	string	How the image was captured (e.g. `"screenshot"`, `"photo"`)
`card_type`	string	Type of the recognized document: `"bank_card"`, `"virtual_card"`, `"bank_statement"`
`cardholder`	string	Recognized cardholder name
`d_uuid`	string	Unique identifier of this document in the X-Faces system
`document_type`	string	Document type code
`expected_name`	bool	Present when the partner-provided `name` is used; indicates whether it matches `cardholder`
`fraud`	bool	Whether fraud indicators were detected
`identity`	string	Unique identifier of this document instance in the X-Faces system
`is_valid`	bool	Whether the project allows this document type
`num`	string	Recognized card or account number (may be partially masked)
`physically_damaged`	bool	Whether the document appears physically damaged
`type`	int	Numerical representation of the document type
`verified`	bool \| null	Cardholder verification result; `null` means no automatic name decision was possible

Bank Card Fields (`card_type: "bank_card"` / `"virtual_card"`)

Field	Type	Description
`bank`	string	Name of the issuing bank
`card_layout`	string	Card layout identifier
`code_is_valid`	bool	Result of Luhn algorithm check on the card number
`exp`	string	Expiration date (MM/YY)
`hide_numbers`	bool	Whether card numbers are hidden/masked in the image
`is_apple_pay`	bool	Whether this is an Apple Pay virtual card
`is_expired`	bool	Whether the card is expired
`is_front_side`	bool	Whether the front side of the card is shown
`is_physical_card`	bool	Whether the card is physical
`is_vertical`	bool	Whether the card has vertical orientation
`system`	string	Payment system (e.g. `"VISA"`, `"MASTERCARD"`)

Bank Statement Fields (`card_type: "bank_statement"`)

Field	Type	Description
`currency`	string	Currency code (e.g. `"RON"`, `"USD"`)
`transaction_amount`	float	Transaction amount
`transaction_date`	string	Transaction date (YYYY-MM-DD)
`transaction_time`	string	Transaction time

Test Request

Headers

token

Params

challenge_id