# Fazer uma venda no PIX

URL: https://staging.pagpolar.com/docs/referencia/vendas/create-pix-payment

> Cria uma cobrança PIX em cima de uma oferta existente. O método de pagamento é definido
pela própria rota, então não é preciso enviar `payment_method` no corpo.

O header `Idempotency-Key` é **obrigatório**. Em caso de timeout, reenvie a requisição
com a mesma chave: a resposta original será devolvida sem gerar uma segunda cobrança.

A resposta desta rota traz o PIX **gerado** (`pix.qr_code`), não o **pago**. A confirmação
do pagamento acontece de forma assíncrona — assine o webhook `TRANSACTION_PAID` para ser
notificado assim que o PIX for pago, ou consulte `GET /sales/{identifier}` usando o
`transactions[0]` da resposta para checar o `status` a qualquer momento.

Esta rota **não cria assinaturas**: mesmo apontando para uma oferta recorrente, o
resultado é sempre uma cobrança avulsa (`subscriptions` sempre vem vazio na resposta).

`POST /payments/pix`

## Autenticação

- Token Bearer no header `Authorization` (esquema `BearerAuth`). Token de acesso devolvido por POST /auth/token. Envie como "Authorization: Bearer <token>". Vale 24 horas.

## Parâmetros de header

| Parâmetro | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `Idempotency-Key` | texto | sim | Exemplo: `2f1c4d2e-8f4a-4c1e-9f7b-6a2d1e3c5b90`. |

## Corpo da requisição

Content-type: `application/json`.

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `offer_identifier` | texto | não | Código de uma oferta existente. Envie este campo **ou** `offer` — nunca os dois. Exemplo: `PPP1234567890`. |
| `offer` | objeto | não | Oferta informada na hora. Envie este objeto **ou** `offer_identifier` — nunca os dois. Reaproveita a oferta com mesmo produto, nome, valor e visibilidade; senão cria. |
| `offer.product_id` | texto (uuid) | sim | Produto da sua conta. |
| `offer.name` | texto | sim | Nome da oferta. Exemplo: `Consultoria avulsa`. |
| `offer.value` | inteiro | sim | Valor em centavos. Mínimo 500 (R$ 5,00). Exemplo: `4990`. |
| `offer.createOffer` | booleano | sim | `true`: oferta visível. `false`: oferta oculta, fora das listagens e usável só por esta API. Exemplo: `false`. |
| `quantity` | inteiro | não | — |
| `affiliate_identifier` | texto | não | Código do afiliado que trouxe a venda, no formato `PAO` seguido de 10 dígitos. Formato inválido retorna `400`. Código de afiliado inexistente, de outro produto, inativo ou sem a oferta liberada é **ignorado**: a venda é processada normalmente, sem afiliado. Não há cookie nem regra de primeiro ou último clique — vale o código enviado. Exemplo: `PAO1234567890`. |
| `external_reference` | texto | não | Referência do pedido no seu sistema (por exemplo, o número do pedido). Opcional. Depois você consulta a venda por ela em `GET /sales/{identifier}` e filtra em `GET /sales?external_reference=`. Pode se repetir entre pedidos: a consulta devolve a venda mais recente com essa referência. Exemplo: `PED-2026-0001`. |
| `customer` | objeto | sim | — |
| `customer.name` | texto | sim | Exemplo: `Fulano de Tal`. |
| `customer.email` | texto (email) | sim | Exemplo: `fulano@exemplo.com`. |
| `customer.document` | texto | sim | CPF (11 dígitos) ou CNPJ (14 dígitos), com ou sem pontuação: `12345678909` ou `123.456.789-09`. A API grava só os dígitos. Fora disso, 400. Exemplo: `12345678909`. |
| `customer.phone` | texto | sim | DDD e número, com 10 ou 11 dígitos (12 ou 13 com o código do país 55). Pontuação, espaços, parênteses e `+` são aceitos: `11999998888`, `(11) 99999-8888` ou `+55 11 99999-8888`. A API grava só os dígitos. Fora disso, 400. Exemplo: `11999999999`. |
| `address` | objeto | não | Obrigatório quando a oferta é de produto físico (`requires_shipping: true`); nos demais casos é opcional e não é usado no processamento da venda. |
| `address.street` | texto | sim | Exemplo: `Rua das Flores`. |
| `address.number` | texto | sim | Exemplo: `123`. |
| `address.complement` | texto | não | Exemplo: `Apto 4B`. Pode ser nulo. |
| `address.neighborhood` | texto | sim | Exemplo: `Centro`. |
| `address.city` | texto | sim | Exemplo: `São Paulo`. |
| `address.state` | texto | sim | Exemplo: `SP`. |
| `address.postal_code` | texto | sim | Exemplo: `01000-000`. |
| `shipping_option_id` | texto | não | Opção de frete escolhida, obrigatória quando a oferta é de produto físico (`requires_shipping: true`). Use o `id` devolvido por `GET /offers/{identifier}/shipping` para o mesmo CEP enviado em `address.postal_code`. Enviar este campo numa oferta que não exige frete retorna `400`. Exemplo: `wil_a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d`. |
| `buyer_ip` | texto | não | IP do comprador final. Melhora a análise antifraude. Exemplo: `203.0.113.10`. |
| `buyer_user_agent` | texto | não | User agent do comprador final. |

### Exemplo do corpo

PIX com offer_identifier (sem offer):

```json
{
  "offer_identifier": "PPP1234567890",
  "customer": {
    "name": "Fulano de Tal",
    "email": "fulano@exemplo.com",
    "document": "12345678909",
    "phone": "11999999999"
  },
  "buyer_ip": "203.0.113.10"
}
```

PIX com offer (sem offer_identifier):

```json
{
  "offer": {
    "product_id": "c4d5e6f7-a8b9-4c0d-1e2f-3a4b5c6d7e8f",
    "name": "Consultoria avulsa",
    "value": 4990,
    "createOffer": false
  },
  "customer": {
    "name": "Fulano de Tal",
    "email": "fulano@exemplo.com",
    "document": "12345678909",
    "phone": "11999999999"
  },
  "buyer_ip": "203.0.113.10"
}
```

## Respostas

### 201 — Pagamento PIX criado

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `data` | [Resultado da cobrança](/docs/referencia/entidades/resultado-da-cobranca) | não | — |

#### Exemplo

PIX:

```json
{
  "data": {
    "offer_identifier": "PPP1234567890",
    "transactions": [
      "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
    ],
    "subscriptions": [],
    "pix": {
      "qr_code": "00020126..."
    }
  }
}
```

## Erros

| Status | Descrição |
| --- | --- |
| `400` | Dados inválidos, Idempotency-Key ausente, número de parcelas acima do limite da oferta, ou documento/telefone fora do formato (CPF 11 dígitos, CNPJ 14, telefone 10 a 13 dígitos) |
| `401` | Token ausente, inválido ou expirado, ou credencial revogada ou expirada. Chame POST /auth/token para obter um token novo. |
| `403` | IP não autorizado |
| `404` | Oferta não encontrada |
| `409` | Oferta inativa/expirada, método não habilitado ou requisição idêntica em processamento |
| `429` | Limite de requisições excedido |
| `503` | Serviço de limite indisponível — repita a requisição com a mesma Idempotency-Key |

Lista completa de códigos e como tratá-los: [Erros](/docs/guias/fundamentos/erros).