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

# Aceitar pagamento na maquininha (POS)

> Integre pagamentos presenciais de ponta a ponta — modo passivo (webhook) e modo ativo (você inicia a venda)

O **POS** permite aceitar pagamentos **presenciais** — o cartão passado numa maquininha física — pela
Autorizou, com o mesmo modelo de dados das vendas online (pagamento, split, extrato) e um bloco extra
que identifica o terminal.

Há **dois modos de integração**, e a diferença é só **quem inicia a venda**:

<CardGroup cols={2}>
  <Card title="Modo Passivo" icon="wave-sine">
    A venda começa **na maquininha** (o operador passa o cartão). A Autorizou te **notifica por
    webhook** quando ela cai, já com os dados do terminal. Você integra **recebendo** o evento.
  </Card>

  <Card title="Modo Ativo" icon="tower-broadcast">
    A venda começa **na sua aplicação** (caixa, comanda, sistema de vendas). Você **chama a
    Autorizou** informando o terminal e o valor; ela dispara a cobrança no aparelho e devolve o
    resultado. Você integra **chamando** o endpoint.
  </Card>
</CardGroup>

Os dois modos podem coexistir para o mesmo lojista, e **convergem no mesmo registro de venda**:
reenvios da mesma venda **não geram cobrança dupla** (idempotência), e a divisão (split) para o
recebedor dono do terminal acontece igual nos dois casos.

```mermaid theme={null}
flowchart LR
    A["Modo passivo<br/>venda começa na maquininha"] --> R["Registro único da venda<br/>idempotente"]
    B["Modo ativo<br/>venda começa na sua aplicação"] --> R
    R --> W["Webhook de saída<br/>com bloco pos"]
    R --> SP["Split para o recebedor do canal"]
```

## Vocabulário

<AccordionGroup>
  <Accordion title="Terminal (maquininha)">
    O aparelho físico. Cada terminal tem um **`code`** (o identificador que liga a venda ao aparelho
    certo), um `serial_number` e um `model`. É o `code` que você usa para iniciar uma venda (modo
    ativo) e para conciliar (modo passivo).
  </Accordion>

  <Accordion title="Vínculo com o recebedor">
    Um terminal é **atribuído** a um recebedor (a loja/clínica que opera o aparelho). Esse vínculo é a
    fonte de verdade de **quem recebe** a venda daquele terminal: a divisão usa o recebedor vinculado
    automaticamente. Você **não** informa recebedor na venda — o terminal resolve. A gestão de
    inventário e vínculos é feita pela Autorizou; pela API você **consome** o resultado.
  </Accordion>

  <Accordion title="Identificador único e idempotência">
    Toda venda presencial carrega um identificador único. A Autorizou registra cada venda **uma só
    vez** por esse identificador: reenvio de webhook ou retry de rede **não** cria uma segunda venda.
    No modo ativo, a idempotência é pela sua `Idempotency-Key`. Faça o mesmo do seu lado —
    **deduplique** sempre.
  </Accordion>
</AccordionGroup>

## Ambientes

| Ambiente | Base URL                             |
| -------- | ------------------------------------ |
| Sandbox  | `https://pay.autorizou.dev/api/v1`   |
| Produção | `https://pay.autorizou.cloud/api/v1` |

Autentique com a sua chave de API no header `Authorization: Bearer aut_...` (a mesma das demais
integrações). A chave já escopa tudo ao seu lojista — você nunca envia `merchant_id`.

***

## Modo Passivo — a venda começa na maquininha

O operador cobra direto no aparelho. Você **não inicia** nada: a Autorizou registra a venda e te
**notifica por webhook**, com o bloco `pos`. É o jeito mais simples de integrar — basta escutar os
eventos.

```mermaid theme={null}
sequenceDiagram
    participant P as Portador do cartão
    participant M as Maquininha
    participant AZ as Autorizou
    participant S as Sua aplicação
    P->>M: passa o cartão
    M-->>AZ: venda aprovada no terminal
    AZ->>AZ: registra a venda (idempotente) + aplica o split do canal
    AZ-->>S: webhook payment.created + payment.authorized (com bloco pos)
```

A venda dispara os eventos normais — `payment.created` e `payment.authorized` — só que o payload traz
o bloco **`pos`**. O contrato completo desse payload está em
[Webhook de Venda no Terminal](/api-reference/pos/pos-webhook).

<Steps>
  <Step title="Configure o webhook e assine os eventos">
    Aponte o seu endpoint e assine, no mínimo, `payment.created` e `payment.authorized`. Veja
    [Configuração de Webhooks](/api-reference/webhooks/configuration).
  </Step>

  <Step title="Reconheça a venda presencial">
    É a **presença do bloco `pos`** que distingue a venda de maquininha de uma venda online.
  </Step>

  <Step title="Deduplique e confirme o estado">
    O webhook é um **gatilho**: deduplique pelo `uuid` e confirme com
    [`GET /payments/{identifier}`](/api-reference/charges/payments/get-payment) antes de agir sobre
    dinheiro/estoque.
  </Step>

  <Step title="Concilie pelo terminal e pela divisão">
    Use `pos.terminal.code` para amarrar a venda ao aparelho e ao ponto de venda. O split para o
    recebedor dono do terminal já acontece automaticamente e vem detalhado no bloco `split` do mesmo
    payload — quem recebeu quanto, no centavo. Veja
    [Split realizado no retorno](/casos-uso/split-pagamento#split-realizado-no-retorno-o-que-você-recebe).
  </Step>
</Steps>

***

## Modo Ativo — a sua aplicação inicia a venda

Quem inicia a venda é a **sua aplicação**: você chama a Autorizou informando o terminal e o valor, ela
dispara a cobrança no aparelho, o portador paga, e **a mesma chamada** devolve o resultado.

```mermaid theme={null}
sequenceDiagram
    participant S as Sua aplicação
    participant AZ as Autorizou
    participant M as Maquininha
    participant P as Portador do cartão
    S->>AZ: POST /pos/sales (terminal + valor + método + parcelas)
    AZ->>AZ: cria a venda POS em initiated
    AZ->>M: dispara a cobrança no terminal
    P->>M: paga
    M-->>AZ: resultado
    AZ->>AZ: venda POS → approved / declined
    AZ-->>S: resposta síncrona (state) + webhook com bloco pos
```

O contrato completo (parâmetros, resposta, cabeçalho de idempotência) está em
[Criar Venda no Terminal](/api-reference/pos/create-pos-sale).

### A máquina de estados

O coração do modo ativo é o ciclo de vida da venda. **Trate cada estado explicitamente.**

```mermaid theme={null}
stateDiagram-v2
    [*] --> initiated: você inicia
    initiated --> approved: aprovada
    initiated --> declined: recusada
    initiated --> aborted: cancelada antes de pagar
    initiated --> unknown: timeout / queda de conexão
    unknown --> approved: recuperação
    unknown --> declined: recuperação
    approved --> [*]
    declined --> [*]
    aborted --> [*]
```

| Estado      | O que significa                                           | O que a sua aplicação faz                                 |
| ----------- | --------------------------------------------------------- | --------------------------------------------------------- |
| `initiated` | Venda criada e enviada ao terminal; aguardando o portador | Mostrar "insira/aproxime o cartão"                        |
| `approved`  | Pagamento aprovado                                        | Concluir a venda; o webhook de pagamento chega em seguida |
| `declined`  | Pagamento recusado                                        | Oferecer nova tentativa (nova `Idempotency-Key`)          |
| `aborted`   | Cancelada antes de pagar (operador/portador desistiu)     | Encerrar sem cobrança                                     |
| `unknown`   | **Não sabemos o resultado ainda** — timeout ou queda      | **Consultar** até resolver; nunca reenviar cego           |

<Warning>
  **A regra de ouro do modo ativo:** `unknown` **não é falha** — é "ainda não sei". Reenviar a venda
  nesse estado pode cobrar o cliente duas vezes. Consulte
  [`GET /pos/sales/{identifier}`](/api-reference/pos/get-pos-sale) até o estado virar `approved` ou
  `declined`; a recuperação resolve. Se precisar repetir a chamada por segurança de rede, use a
  **mesma** `Idempotency-Key`.
</Warning>

***

## Estornos e contestações

Uma venda de maquininha pode ser desfeita como qualquer venda. O reverso chega pelos **eventos normais
de webhook** — a origem presencial continua reconhecível pelo bloco `pos`.

| Reverso                  | Evento que você recebe                                           | Estado final         |
| ------------------------ | ---------------------------------------------------------------- | -------------------- |
| Cancelamento             | [`payment.canceled`](/api-reference/webhooks/events)             | `canceled`           |
| Reembolso total          | [`payment.refunded`](/api-reference/webhooks/events)             | `refunded`           |
| Reembolso parcial        | [`payment.refunded`](/api-reference/webhooks/events)             | `refunded_partially` |
| Contestação (chargeback) | [`payment.chargeback_requested`](/api-reference/webhooks/events) | `chargeback`         |

<Note>
  Um estorno pode partir do **próprio terminal** (o operador estorna no aparelho), sem você pedir — a
  Autorizou registra e te avisa igual. Em todo reverso a Autorizou mantém o extrato coerente: o valor
  sai do saldo, o split é desfeito na proporção correta e nada "some". Você só reflete o novo estado.
</Note>

## Checklist de "estou pronto"

<Check>Recebo `payment.created` e `payment.authorized` e reconheço a venda de maquininha pelo bloco `pos`.</Check>
<Check>Dedupliquei pelo `uuid` da venda e pelo ID do evento.</Check>
<Check>Confirmo o estado com `GET /payments/{identifier}` antes de agir sobre dinheiro/estoque.</Check>
<Check>Concilio pelo `pos.terminal.code`.</Check>
<Check>Trato reembolso, cancelamento e chargeback.</Check>
<Check>No modo ativo, envio `Idempotency-Key` e trato o estado `unknown` (consultar, nunca reenviar cego).</Check>

<Note>
  Referência da API: [Criar Venda no Terminal](/api-reference/pos/create-pos-sale) ·
  [Consultar Venda no Terminal](/api-reference/pos/get-pos-sale) ·
  [Webhook de Venda no Terminal](/api-reference/pos/pos-webhook).
</Note>