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

# Criar Transação

> Cria uma nova transação de pagamento no sistema KlivoPay

## Visão Geral

Uma transação representa uma operação de pagamento no sistema KlivoPay. Cada transação possui um identificador único (hash) e passa por diferentes status durante seu ciclo de vida:

* `pending` - Aguardando pagamento
* `paid` - Pagamento confirmado
* `canceled` - Cancelada
* `refunded` - Reembolsada

## Métodos de Pagamento Suportados

<CardGroup cols={3}>
  <Card title="PIX" icon="qrcode">
    Pagamento instantâneo via QR Code ou Copia e Cola
  </Card>

  <Card title="Cartão de Crédito" icon="credit-card">
    Aprovação imediata com suporte a parcelamento
  </Card>

  <Card title="Boleto Bancário" icon="barcode">
    Pagamento com prazo de vencimento configurável
  </Card>
</CardGroup>

## Endpoint

```
POST https://api.klivopay.com.br/api/public/v1/transactions
```

## Parâmetros

### Obrigatórios

<ParamField body="api_token" type="string" required>
  Seu token de autenticação da API KlivoPay
</ParamField>

<ParamField body="amount" type="integer" required>
  Valor da transação em centavos. Exemplo: R\$ 150,00 = `15000`
</ParamField>

<ParamField body="offer_hash" type="string" required>
  Hash identificador da oferta do produto
</ParamField>

<ParamField body="payment_method" type="string" required>
  Método de pagamento: `pix`, `credit_card` ou `billet`
</ParamField>

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

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

    <ParamField body="customer.email" type="string" required>
      E-mail do cliente
    </ParamField>

    <ParamField body="customer.phone_number" type="string" required>
      Telefone apenas números (DDD + número)
    </ParamField>

    <ParamField body="customer.document" type="string" required>
      CPF ou CNPJ apenas números
    </ParamField>
  </Expandable>
</ParamField>

### Opcionais

<ParamField body="cart" type="array">
  Array de itens do carrinho com detalhes dos produtos
</ParamField>

<ParamField body="installments" type="integer">
  Número de parcelas para cartão de crédito (1 a 12)
</ParamField>

<ParamField body="expire_in_days" type="integer">
  Dias para vencimento do boleto (padrão: 3 dias)
</ParamField>

<ParamField body="postback_url" type="string">
  URL para receber notificações de mudança de status
</ParamField>

<ParamField body="address" type="object">
  Endereço de entrega (opcional para produtos digitais, recomendado para físicos)
</ParamField>

## Exemplo de Requisição

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST 'https://api.klivopay.com.br/api/public/v1/transactions' \
    -H 'Content-Type: application/json' \
    -d '{
      "api_token": "seu_token_aqui",
      "amount": 15000,
      "offer_hash": "abc123def456",
      "payment_method": "pix",
      "customer": {
        "name": "João Silva",
        "email": "joao@example.com",
        "phone_number": "11987654321",
        "document": "12345678900"
      },
      "cart": [
        {
          "name": "Produto Exemplo",
          "quantity": 1,
          "unit_price": 15000
        }
      ]
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.klivopay.com.br/api/public/v1/transactions', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      api_token: 'seu_token_aqui',
      amount: 15000,
      offer_hash: 'abc123def456',
      payment_method: 'pix',
      customer: {
        name: 'João Silva',
        email: 'joao@example.com',
        phone_number: '11987654321',
        document: '12345678900'
      }
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  url = 'https://api.klivopay.com.br/api/public/v1/transactions'
  payload = {
      'api_token': 'seu_token_aqui',
      'amount': 15000,
      'offer_hash': 'abc123def456',
      'payment_method': 'pix',
      'customer': {
          'name': 'João Silva',
          'email': 'joao@example.com',
          'phone_number': '11987654321',
          'document': '12345678900'
      }
  }

  response = requests.post(url, json=payload)
  print(response.json())
  ```

  ```php PHP theme={null}
  <?php
  $url = 'https://api.klivopay.com.br/api/public/v1/transactions';
  $data = [
      'api_token' => 'seu_token_aqui',
      'amount' => 15000,
      'offer_hash' => 'abc123def456',
      'payment_method' => 'pix',
      'customer' => [
          'name' => 'João Silva',
          'email' => 'joao@example.com',
          'phone_number' => '11987654321',
          'document' => '12345678900'
      ]
  ];

  $options = [
      'http' => [
          'header'  => "Content-Type: application/json\r\n",
          'method'  => 'POST',
          'content' => json_encode($data)
      ]
  ];

  $context  = stream_context_create($options);
  $result = file_get_contents($url, false, $context);
  $response = json_decode($result);
  print_r($response);
  ?>
  ```
</CodeGroup>

## Resposta de Sucesso

```json 201 Created theme={null}
{
  "success": true,
  "data": {
    "hash": "abc123def456ghi789",
    "status": "pending",
    "amount": 15000,
    "payment_method": "pix",
    "pix_qr_code": "00020126580014br.gov.bcb.pix...",
    "pix_copy_paste": "00020126580014br.gov.bcb.pix...",
    "created_at": "2025-01-20T10:15:00Z",
    "expires_at": "2025-01-20T10:30:00Z"
  }
}
```

## Códigos de Resposta

<ResponseField name="201" type="Created">
  Transação criada com sucesso
</ResponseField>

<ResponseField name="400" type="Bad Request">
  Dados inválidos na requisição
</ResponseField>

<ResponseField name="401" type="Unauthorized">
  Token de API inválido ou ausente
</ResponseField>

<ResponseField name="422" type="Unprocessable Entity">
  Erro de validação nos dados enviados
</ResponseField>

<ResponseField name="500" type="Internal Server Error">
  Erro interno do servidor
</ResponseField>

## Webhook / Postback

Quando o status da transação mudar, você receberá uma notificação no `postback_url` configurado:

```json theme={null}
{
  "transaction_hash": "abc123def456ghi789",
  "status": "paid",
  "amount": 15000,
  "payment_method": "pix",
  "paid_at": "2025-01-20T10:20:00Z"
}
```

<Note>
  Configure o `postback_url` para receber atualizações automáticas sobre mudanças no status das transações.
</Note>