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"
}

• 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

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": "FINGERPRINTS",
        "cardholder": "ELIN ANDERSSON",
        "code_is_valid": false,
        "d_uuid": "d6e70267-8cd9-4d83-a589-8ecb7dcfa98e",
        "document_type": "rou_bcard",
        "exp": "01/19",
        "identity": "rou_bcard-d6e70267-8cd9-4d83-a589-8ecb7dcfa98e",
        "is_expired": true,
        "is_valid": true,
        "num": "19872654545109",
        "system": "MASTERCARD",
        "type": 110
      },
      "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
}

• bank: recognized name of the bank that has issued the card
• cardholder: recognized cardholder’s name
• code_is_valid: result of Luhn’s algorithm check for whether the card has a valid code number
• d_uuid: unique identifier of the bank card in the X-Faces system
• document_type: type of the document
• exp: recognized expiration date
• identity: unique identifier of this bank card in the X-Faces system
• is_expired: whether the card is expired
• is_valid: whether the project allows such document type
• num: recognized bank card code number
• system: recognized payment system
• type: numerical representation of the document type in the X-Faces system

Test Request

Headers

token

Params

challenge_id

Send API