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

# Criar Checkout Session

> Crie links de pagamento programaticamente com dados do cliente pré-preenchidos

## Visão Geral

Cria uma nova checkout session e retorna uma URL de pagamento. Para entender quando e como usar Checkout Sessions, consulte o [guia completo](/guias/checkout-sessions).

## Headers

<ParamField header="Authorization" type="string" required>
  Sua chave de API (`Bearer YOUR_API_KEY`)
</ParamField>

<ParamField header="Content-Type" type="string" required>
  `application/json`
</ParamField>

<ParamField header="X-Idempotency-Key" type="string">
  Chave única para evitar requisições duplicadas (válida por 24h)
</ParamField>

## Request Body

### Campo Obrigatório

<ParamField body="product_id" type="integer" required>
  ID do produto a ser vendido
</ParamField>

### Campos Opcionais

<ParamField body="price_id" type="string">
  ID do preço de assinatura (para pagamentos recorrentes)
</ParamField>

<ParamField body="customer" type="object">
  Dados do cliente para pré-preencher o formulário de checkout

  <Expandable title="Campos do customer">
    <ParamField body="customer.name" type="string">
      Nome completo do cliente (máx 255 caracteres)
    </ParamField>

    <ParamField body="customer.email" type="string">
      Email do cliente (máx 255 caracteres)
    </ParamField>

    <ParamField body="customer.document" type="string">
      CPF ou CNPJ (máx 14 caracteres, apenas números)
    </ParamField>

    <ParamField body="customer.phone" type="string">
      Telefone (máx 11 caracteres, apenas números)
    </ParamField>

    <ParamField body="customer.zip_code" type="string">
      CEP (máx 8 caracteres, apenas números)
    </ParamField>

    <ParamField body="customer.street" type="string">
      Rua (máx 255 caracteres)
    </ParamField>

    <ParamField body="customer.number" type="string">
      Número do endereço (máx 20 caracteres)
    </ParamField>

    <ParamField body="customer.complement" type="string">
      Complemento (máx 255 caracteres)
    </ParamField>

    <ParamField body="customer.neighborhood" type="string">
      Bairro (máx 100 caracteres)
    </ParamField>

    <ParamField body="customer.city" type="string">
      Cidade (máx 100 caracteres)
    </ParamField>

    <ParamField body="customer.state" type="string">
      Estado (2 letras, ex: "SP")
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="payment_methods" type="array">
  Restringe os métodos de pagamento disponíveis. Valores aceitos: `pix`, `creditCard`, `boleto`
</ParamField>

<ParamField body="metadata" type="object">
  Dados personalizados para seu uso (máx 50 chaves, 500 caracteres por valor)
</ParamField>

<ParamField body="success_url" type="string">
  URL de redirecionamento após pagamento bem-sucedido (máx 500 caracteres). Use `{SESSION_ID}` como placeholder.
</ParamField>

<ParamField body="cancel_url" type="string">
  URL de redirecionamento se o cliente cancelar (máx 500 caracteres)
</ParamField>

<ParamField body="client_reference_id" type="string">
  Seu ID de referência interno (máx 200 caracteres)
</ParamField>

<ParamField body="affiliate_id" type="integer">
  ID do afiliado para atribuição de comissão
</ParamField>

<ParamField body="expires_at" type="string">
  Data de expiração da session (ISO 8601). Padrão: 24 horas após criação
</ParamField>

## Exemplo de Requisição

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.garu.com.br/api/checkout/sessions \
    -H "Authorization: Bearer sk_test_sua_chave_api" \
    -H "Content-Type: application/json" \
    -H "X-Idempotency-Key: order_12345_checkout" \
    -d '{
      "product_id": 123,
      "customer": {
        "name": "João Silva",
        "email": "joao@email.com"
      },
      "success_url": "https://seusite.com/sucesso?session_id={SESSION_ID}",
      "cancel_url": "https://seusite.com/cancelado",
      "metadata": {
        "order_id": "12345"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.garu.com.br/api/checkout/sessions', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer ' + process.env.GARU_API_KEY,
      'Content-Type': 'application/json',
      'X-Idempotency-Key': 'order_' + Date.now()
    },
    body: JSON.stringify({
      product_id: 123,
      customer: {
        name: 'João Silva',
        email: 'joao@email.com'
      },
      success_url: 'https://seusite.com/sucesso?session_id={SESSION_ID}',
      cancel_url: 'https://seusite.com/cancelado',
      metadata: { order_id: '12345' }
    })
  });

  const { data } = await response.json();
  // Redirecionar cliente para data.url
  ```

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

  response = requests.post(
      'https://api.garu.com.br/api/checkout/sessions',
      headers={
          'Authorization': 'Bearer ' + os.environ['GARU_API_KEY'],
          'X-Idempotency-Key': 'order_12345_checkout'
      },
      json={
          'product_id': 123,
          'customer': {
              'name': 'João Silva',
              'email': 'joao@email.com'
          },
          'success_url': 'https://seusite.com/sucesso?session_id={SESSION_ID}',
          'cancel_url': 'https://seusite.com/cancelado',
          'metadata': {'order_id': '12345'}
      }
  )

  data = response.json()['data']
  # Redirecionar cliente para data['url']
  ```
</CodeGroup>

## Resposta de Sucesso

<ResponseField name="id" type="string">
  Identificador único da session (ex: `cs_ABC123xyz`)
</ResponseField>

<ResponseField name="status" type="string">
  Status da session: `open`, `complete` ou `expired`
</ResponseField>

<ResponseField name="url" type="string">
  URL do checkout para redirecionar o cliente
</ResponseField>

<ResponseField name="product_id" type="integer">
  ID do produto
</ResponseField>

<ResponseField name="price_id" type="string">
  ID do preço de assinatura (se aplicável)
</ResponseField>

<ResponseField name="customer_email" type="string">
  Email do cliente pré-preenchido
</ResponseField>

<ResponseField name="customer_name" type="string">
  Nome do cliente pré-preenchido
</ResponseField>

<ResponseField name="metadata" type="object">
  Seus metadados personalizados
</ResponseField>

<ResponseField name="success_url" type="string">
  URL de redirecionamento de sucesso
</ResponseField>

<ResponseField name="cancel_url" type="string">
  URL de redirecionamento de cancelamento
</ResponseField>

<ResponseField name="client_reference_id" type="string">
  Seu ID de referência
</ResponseField>

<ResponseField name="affiliate_id" type="integer">
  ID do afiliado
</ResponseField>

<ResponseField name="transaction_id" type="integer">
  ID da transação (preenchido quando completa)
</ResponseField>

<ResponseField name="expires_at" type="string">
  Data de expiração (ISO 8601)
</ResponseField>

<ResponseField name="completed_at" type="string">
  Data de conclusão (ISO 8601, null se não completa)
</ResponseField>

<ResponseField name="created_at" type="string">
  Data de criação (ISO 8601)
</ResponseField>

### Exemplo de Resposta (201 Created)

```json theme={null}
{
  "data": {
    "id": "cs_ABC123xyz",
    "status": "open",
    "url": "https://pay.garu.com.br/pay/session/abc123...",
    "product_id": 123,
    "price_id": null,
    "customer_email": "joao@email.com",
    "customer_name": "João Silva",
    "metadata": {
      "order_id": "12345"
    },
    "success_url": "https://seusite.com/sucesso?session_id={SESSION_ID}",
    "cancel_url": "https://seusite.com/cancelado",
    "client_reference_id": null,
    "affiliate_id": null,
    "transaction_id": null,
    "expires_at": "2025-01-20T12:00:00.000Z",
    "completed_at": null,
    "created_at": "2025-01-19T12:00:00.000Z"
  }
}
```

## Erros Comuns

<AccordionGroup>
  <Accordion title="400 - product_id obrigatório">
    ```json theme={null}
    {
      "statusCode": 400,
      "message": "product_id is required",
      "error": "Bad Request"
    }
    ```

    **Solução:** Inclua o campo `product_id` na requisição.
  </Accordion>

  <Accordion title="400 - Método de pagamento inválido">
    ```json theme={null}
    {
      "statusCode": 400,
      "message": "Invalid payment method",
      "error": "Bad Request"
    }
    ```

    **Solução:** Use apenas valores válidos em `payment_methods`: `pix`, `creditCard`, `boleto`.
  </Accordion>

  <Accordion title="401 - Não autorizado">
    ```json theme={null}
    {
      "statusCode": 401,
      "message": "Unauthorized"
    }
    ```

    **Solução:** Verifique se o header `Authorization` está correto.
  </Accordion>

  <Accordion title="404 - Produto não encontrado">
    ```json theme={null}
    {
      "statusCode": 404,
      "message": "Product not found"
    }
    ```

    **Solução:** Verifique se o `product_id` existe e pertence ao seu vendedor.
  </Accordion>

  <Accordion title="429 - Rate limit excedido">
    ```json theme={null}
    {
      "statusCode": 429,
      "message": "Too Many Requests"
    }
    ```

    **Solução:** Aguarde antes de fazer novas requisições. Limite: 100 requisições por minuto.
  </Accordion>
</AccordionGroup>

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Guia de Checkout Sessions" icon="book" href="/guias/checkout-sessions">
    Entenda quando e como usar
  </Card>

  <Card title="Listar Sessions" icon="list" href="/api-reference/checkout/listar">
    Consulte suas sessions
  </Card>
</CardGroup>