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

# Criar Transacao

> Cria uma nova transacao de pagamento (PIX, Boleto ou Cartao)

## Descricao

Cria uma transacao de pagamento. Para PIX, retorna QR Code. Para Boleto, retorna codigo de barras. Para Cartao, processa a cobranca imediatamente.

<Warning>
  Requer header `Idempotency-Key` com UUID v4 unico. Veja o [guia de idempotencia](/guides/idempotency).
</Warning>

## Request

### Headers

<ParamField header="Idempotency-Key" type="string" required>
  UUID v4 unico para garantir idempotencia. Exemplo: `550e8400-e29b-41d4-a716-446655440000`
</ParamField>

### Body

<ParamField body="amount" type="integer" required>
  Valor total em **centavos**. Minimo: 100 (R$ 1,00). Exemplo: R$ 15,00 = `1500`
</ParamField>

<ParamField body="method" type="string" required>
  Metodo de pagamento. Valores: `PIX`, `BOLETO`, `CREDIT_CARD`
</ParamField>

<ParamField body="customer" type="object" required>
  Dados do comprador.

  <Expandable title="Campos do customer">
    <ParamField body="customer.name" type="string" required>
      Nome completo do comprador.
    </ParamField>

    <ParamField body="customer.email" type="string" required>
      Email valido do comprador.
    </ParamField>

    <ParamField body="customer.phone" type="string" required>
      Telefone com DDD (apenas digitos). Exemplo: `11999999999`
    </ParamField>

    <ParamField body="customer.documentType" type="string" required>
      Tipo do documento. Valores: `CPF`, `CNPJ`
    </ParamField>

    <ParamField body="customer.document" type="string" required>
      Numero do documento (apenas digitos). CPF: 11 digitos, CNPJ: 14 digitos.
    </ParamField>

    <ParamField body="customer.externalRef" type="string">
      Referencia externa do cliente no seu sistema (max 128 chars).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="items" type="array" required>
  Lista de itens da transacao.

  <Expandable title="Campos de cada item">
    <ParamField body="items[].title" type="string" required>
      Nome do produto/servico.
    </ParamField>

    <ParamField body="items[].amount" type="integer" required>
      Preco unitario em centavos.
    </ParamField>

    <ParamField body="items[].quantity" type="integer" required>
      Quantidade (minimo 1).
    </ParamField>

    <ParamField body="items[].tangible" type="boolean" required>
      `true` para produto fisico, `false` para digital/servico.
    </ParamField>

    <ParamField body="items[].externalRef" type="string">
      SKU ou referencia do item (max 128 chars).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="card" type="object">
  Dados do cartao. **Obrigatorio** quando `method` = `CREDIT_CARD`.

  <Expandable title="Campos do card">
    <ParamField body="card.number" type="string" required>
      Numero do cartao (apenas digitos, sem espacos).
    </ParamField>

    <ParamField body="card.holderName" type="string" required>
      Nome impresso no cartao.
    </ParamField>

    <ParamField body="card.expirationMonth" type="integer" required>
      Mes de validade (1-12).
    </ParamField>

    <ParamField body="card.expirationYear" type="integer" required>
      Ano de validade (4 digitos, ex: 2028).
    </ParamField>

    <ParamField body="card.cvv" type="string" required>
      Codigo de seguranca (3-4 digitos). Nunca armazenado apos autorizacao.
    </ParamField>

    <ParamField body="card.holderDocument" type="string">
      CPF/CNPJ do portador do cartao (apenas digitos).
    </ParamField>

    <ParamField body="card.token" type="string">
      Token de cartao previamente tokenizado (substitui number/cvv).
    </ParamField>

    <ParamField body="card.sessionId" type="string">
      ID de sessao do SDK antifraude.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="installments" type="integer">
  Numero de parcelas (1-12). Obrigatorio para `CREDIT_CARD`.
</ParamField>

<ParamField body="metadata" type="object">
  JSON com dados customizados (max 10 chaves). Exemplo: `{"orderId": "ORD-001"}`
</ParamField>

<ParamField body="description" type="string">
  Descricao da transacao.
</ParamField>

<ParamField body="postbackUrl" type="string">
  URL alternativa para receber webhook desta transacao (HTTPS).
</ParamField>

<ParamField body="expiration" type="integer">
  Tempo de expiracao em segundos (para PIX e Boleto).
</ParamField>

<RequestExample>
  ```bash PIX theme={null}
  curl -X POST https://api.thalbank.com/transactions \
    -H "x-api-key: sua_api_key" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
    -d '{
      "amount": 5000,
      "method": "PIX",
      "customer": {
        "name": "Maria Silva",
        "email": "maria@email.com",
        "phone": "11999999999",
        "documentType": "CPF",
        "document": "12345678901"
      },
      "items": [
        {
          "title": "Assinatura Mensal",
          "amount": 5000,
          "quantity": 1,
          "tangible": false
        }
      ],
      "metadata": { "planId": "premium" }
    }'
  ```

  ```bash Cartao de Credito theme={null}
  curl -X POST https://api.thalbank.com/transactions \
    -H "x-api-key: sua_api_key" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: 660e8400-e29b-41d4-a716-446655440001" \
    -d '{
      "amount": 15000,
      "method": "CREDIT_CARD",
      "installments": 3,
      "customer": {
        "name": "Joao Souza",
        "email": "joao@email.com",
        "phone": "21988888888",
        "documentType": "CPF",
        "document": "98765432100"
      },
      "items": [
        {
          "title": "Curso Online",
          "amount": 15000,
          "quantity": 1,
          "tangible": false
        }
      ],
      "card": {
        "number": "4111111111111111",
        "holderName": "JOAO SOUZA",
        "expirationMonth": 12,
        "expirationYear": 2028,
        "cvv": "123"
      }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 PIX theme={null}
  {
    "status": true,
    "data": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "amount": 5000,
      "method": "PIX",
      "status": "PENDING",
      "pixQrCode": "00020126580014br.gov.bcb.pix...",
      "pixQrCodeBase64": "data:image/png;base64,iVBORw0KGgo...",
      "expiresAt": "2026-03-10T01:00:00.000Z",
      "customer": {
        "name": "Maria Silva",
        "email": "maria@email.com"
      },
      "metadata": { "planId": "premium" },
      "createdAt": "2026-03-10T00:00:00.000Z"
    }
  }
  ```

  ```json 201 Cartao theme={null}
  {
    "status": true,
    "data": {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "amount": 15000,
      "method": "CREDIT_CARD",
      "status": "PAID",
      "installments": 3,
      "customer": {
        "name": "Joao Souza",
        "email": "joao@email.com"
      },
      "paidAt": "2026-03-10T00:00:01.000Z",
      "createdAt": "2026-03-10T00:00:00.000Z"
    }
  }
  ```

  ```json 400 theme={null}
  {
    "statusCode": 400,
    "message": ["amount must not be less than 100"],
    "error": "Bad Request"
  }
  ```
</ResponseExample>