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",
  "callback_url": "string",
  "image": "string base64" | ["string base64", "..."]
}

• user_external_id: user identifier in the external system
• expected_number: bank card’s code number, the digits of the number can be replaced with a wildcard, e.g.: 1111 **** 2222 3333, any non-digit character can be used as a wildcard. Spaces and hyphenation are ignored.
• 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

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

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",
        "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: "virtual_card", "physical_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
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	Verification result

Bank Card Fields (card_type: "virtual_card" / "physical_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

Send API