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

# Criar transação

> Inicia o fluxo do TrustPass: valida a titularidade do cartão, verifica passkey e retorna a URL de checkout para redirecionar o comprador.

Este é o endpoint que **inicia o fluxo do TrustPass**. Sua aplicação (o lojista) chama este endpoint **server-to-server**, antes de o comprador chegar à tela de checkout — normalmente no momento em que o pedido é fechado no seu carrinho.

Ao criar a transação, o TrustPass já executa a validação de titularidade ([Card Check](/plataforma/card-check/apresentacao)) e a verificação de passkey de forma síncrona. Se algum desses serviços estiver indisponível, a criação **não falha**: o sinal correspondente volta como ausente (`validated: false` / `hasPasskey: false`) e a transação segue criada normalmente.

<Note>
  Os sinais de dispositivo (Shield) **não** são coletados neste endpoint — a criação acontece antes de o comprador chegar ao front-end do TrustPass. Eles são anexados depois, a partir da tela de checkout, via `PATCH /transactions/{id}/device`.
</Note>

## Request Body

<ParamField body="identity" type="object" required>
  Documento do comprador informado no seu checkout.

  <Expandable title="propriedades">
    <ParamField body="key" type="string" required>
      Tipo de documento: `cpf` ou `cnpj`.

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

    <ParamField body="value" type="string" required>
      Número do documento (CPF com 11 dígitos ou CNPJ com 14 dígitos), sem formatação.

      **Exemplo**: `12345678062`
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="card" type="object" required>
  Dados do cartão utilizado na compra.

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

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

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

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

    <ParamField body="holder_name" type="string" required>
      Nome do titular do cartão, como impresso.

      **Exemplo**: `MARIA DE SOUZA`
    </ParamField>

    <ParamField body="expiration_date" type="string">
      Validade do cartão. Opcional.

      **Exemplo**: `12/29`
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="order_number" type="string" required>
  Identificador do pedido no seu sistema. Não precisa ser único.

  **Exemplo**: `PED-9981`
</ParamField>

<ParamField body="amount" type="number" required>
  Valor da compra. Deve ser maior que zero.

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

<ParamField body="merchant_name" type="string" required>
  Nome do lojista, exibido na tela de checkout do comprador.

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

<ParamField body="currency" type="string">
  Código de moeda ISO 4217. Opcional — padrão `BRL`.

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

<ParamField body="buyer_name" type="string">
  Nome de quem está fazendo a compra (o comprador, que pode não ser o titular do cartão). Opcional.

  **Exemplo**: `MARIA DE SOUZA`
</ParamField>

<ParamField body="redirect_url" type="string">
  URL para onde o comprador é redirecionado ao final do fluxo. Opcional.

  **Exemplo**: `https://minhaloja.exemplo/retorno`
</ParamField>

<ParamField body="purchased_at" type="string">
  Data e hora da compra (ISO 8601). Opcional — se omitido, usa o momento da criação.

  **Exemplo**: `2026-08-03T12:00:00.000Z`
</ParamField>

<ParamField body="billing_profile" type="string">
  Perfil de cobrança usado na chamada ao Card Check. Opcional.

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

## Response

<ResponseField name="transactionId" type="string">
  ID da transação criada. Use para consultar o [status](/plataforma/trustpass/api/get-transacao) e a [inteligência da transação](/plataforma/trustpass/api/get-transacao-inteligencia).
</ResponseField>

<ResponseField name="status" type="string">
  Sempre `pending` na criação. Veja a [lista completa de status](/plataforma/trustpass/fluxo-titular-terceiro#status-da-transação).
</ResponseField>

<ResponseField name="validated" type="boolean">
  Resultado do Card Check nesta criação. `false` também quando o Card Check estiver indisponível.
</ResponseField>

<ResponseField name="hasPasskey" type="boolean">
  Indica se o titular já possui uma passkey cadastrada.
</ResponseField>

<ResponseField name="buyerName" type="string">
  Nome do comprador informado na criação. `null` quando não enviado.
</ResponseField>

<ResponseField name="masked" type="string">
  Documento do comprador, mascarado.

  **Exemplo**: `473.***.***-47`
</ResponseField>

<ResponseField name="payment" type="object">
  Resumo da compra.

  <Expandable title="Propriedades de payment">
    <ResponseField name="merchant" type="string">
      Nome do lojista.
    </ResponseField>

    <ResponseField name="amount" type="number">
      Valor da compra.
    </ResponseField>

    <ResponseField name="currency" type="string">
      Moeda da compra.
    </ResponseField>

    <ResponseField name="cardLast4" type="string">
      Últimos 4 dígitos do cartão.
    </ResponseField>

    <ResponseField name="purchasedAt" type="string">
      Data e hora da compra.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="expiresAt" type="string">
  Data e hora em que a transação expira (30 minutos após a criação).
</ResponseField>

<ResponseField name="checkoutUrl" type="string">
  URL do checkout web do TrustPass. Redirecione o comprador para esta URL — ela já contém o `transaction_id` e a sua `x-api-key` (cifrada) como parâmetro.

  **Exemplo**: `https://checkout.trustpass.exemplo/?transaction_id=a1b2...&key=enc.<iv>.<ct>`
</ResponseField>

<ResponseExample>
  ```json 201 theme={"theme":"catppuccin-latte"}
  {
    "transactionId": "a1b2c3d4-e5f6-7890-abcd-ef0123456789",
    "buyerName": "MARIA DE SOUZA",
    "status": "pending",
    "validated": true,
    "hasPasskey": false,
    "masked": "473.***.***-47",
    "payment": {
      "merchant": "MinhaLoja",
      "amount": 199.9,
      "currency": "BRL",
      "cardLast4": "7890",
      "purchasedAt": "2026-08-03T12:00:00.000Z"
    },
    "expiresAt": "2026-08-03T12:30:00.000Z",
    "checkoutUrl": "https://checkout.trustpass.exemplo/?transaction_id=a1b2c3d4-e5f6-7890-abcd-ef0123456789&key=enc.<iv>.<ct>"
  }
  ```

  ```json 400 theme={"theme":"catppuccin-latte"}
  {
    "code": "INVALID_INPUT",
    "field": "card.bin_digits",
    "reason": "bin_digits must be exactly 6 digits"
  }
  ```
</ResponseExample>

## Códigos de erro

| Código HTTP | `code`          | Descrição                                                                                                                   |
| :---------- | :-------------- | :-------------------------------------------------------------------------------------------------------------------------- |
| 400         | `INVALID_INPUT` | Campo inválido (documento, BIN, últimos 4 dígitos ou valor da compra malformados). O corpo do erro traz `field` e `reason`. |
| 401         | —               | API key ausente ou inválida.                                                                                                |