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

# Validar titularidade de cartão

> Verifique se o documento (CPF/CNPJ) informado é o titular do cartão (BIN + last4). A resposta é idempotente por transaction_id.

## Request Body

<ParamField body="billing_profile" type="string" required>
  Modelo de cobrança associado a esta requisição. Valores possíveis: `TRANSACTIONAL`, `INCLUDED_IN_BUNDLE`.

  **Exemplo**: `TRANSACTIONAL`
</ParamField>

<ParamField body="document" type="string" required>
  Documento do portador do cartão: CPF (11 dígitos) ou CNPJ (14 dígitos), sem formatação.

  **Padrão**: `^\d{11}(\d{3})?$`

  **Exemplo**: `12345678909`
</ParamField>

<ParamField body="card_bin" type="string" required>
  BIN do cartão (6 dígitos).

  **Padrão**: `^\d{6}$`

  **Exemplo**: `450903`
</ParamField>

<ParamField body="card_last_4" type="string" required>
  Últimos 4 dígitos do cartão.

  **Padrão**: `^\d{4}$`

  **Exemplo**: `1234`
</ParamField>

<ParamField body="transaction_id" type="string" required>
  Identificador único da transação (usado para idempotência). 8 a 64 caracteres alfanuméricos, ponto, hífen ou underscore.

  **Padrão**: `^[A-Za-z0-9._-]{8,64}$`

  **Exemplo**: `tx-a1b2c3d4-e5f6`
</ParamField>

## Response

<ResponseField name="match" type="boolean">
  `true` se o documento é titular do cartão informado.

  **Exemplo**: `true`
</ResponseField>

<ResponseField name="request_id" type="string">
  ID único desta requisição.

  **Exemplo**: `valid-req-550e8400-e29b`
</ResponseField>

<ResponseField name="timestamp" type="string">
  Timestamp UTC da resposta.

  **Exemplo**: `2026-05-06T17:00:00.000Z`
</ResponseField>

<ResponseExample>
  ```json 200 theme={"theme":"catppuccin-latte"}
  {
    "match": true,
    "request_id": "valid-req-550e8400-e29b",
    "timestamp": "2026-05-06T17:00:00.000Z"
  }
  ```

  ```json 400 theme={"theme":"catppuccin-latte"}
  {
    "statusCode": 400,
    "code": "INVALID_INPUT",
    "field": "card_bin",
    "reason": "card_bin must be exactly 6 digits",
    "timestamp": "2026-05-06T17:00:00.000Z",
    "path": "/banking/validate-ownership"
  }
  ```

  ```json 401 theme={"theme":"catppuccin-latte"}
  {
    "statusCode": 401,
    "message": "Unauthorized",
    "timestamp": "2026-05-06T17:00:00.000Z",
    "path": "/banking/validate-ownership"
  }
  ```

  ```json 404 theme={"theme":"catppuccin-latte"}
  {
    "statusCode": 404,
    "code": "NO_ADAPTER_FOUND",
    "bin": "999999",
    "timestamp": "2026-05-06T17:00:00.000Z",
    "path": "/banking/validate-ownership"
  }
  ```

  ```json 504 theme={"theme":"catppuccin-latte"}
  {
    "statusCode": 504,
    "code": "BANK_TIMEOUT",
    "timestamp": "2026-05-06T17:00:00.000Z",
    "path": "/banking/validate-ownership"
  }
  ```
</ResponseExample>

## Códigos de erro

| Código HTTP | `code`                               | Descrição                                               |
| :---------- | :----------------------------------- | :------------------------------------------------------ |
| 400         | `INVALID_INPUT`                      | Campos inválidos (documento, BIN ou last4 malformados). |
| 401         | —                                    | API key ausente ou inválida.                            |
| 404         | `NO_ADAPTER_FOUND`                   | Nenhum adapter registrado para o BIN informado.         |
| 504         | `BANK_TIMEOUT` \| `BANK_UNREACHABLE` | Timeout ou falha na comunicação com o banco emissor.    |