Skip to main content
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:

Modo Passivo

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.

Modo Ativo

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.
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.

​
Vocabulário

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).
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.
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.

​
Ambientes

AmbienteBase URL
Sandboxhttps://pay.autorizou.dev/api/v1
Produçãohttps://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. 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.
1

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.
2

Reconheça a venda presencial

É a presença do bloco pos que distingue a venda de maquininha de uma venda online.
3

Deduplique e confirme o estado

O webhook é um gatilho: deduplique pelo uuid e confirme com GET /payments/{identifier} antes de agir sobre dinheiro/estoque.
4

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.

​
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. O contrato completo (parâmetros, resposta, cabeçalho de idempotência) está em Criar Venda no Terminal.

​
A máquina de estados

O coração do modo ativo é o ciclo de vida da venda. Trate cada estado explicitamente.
EstadoO que significaO que a sua aplicação faz
initiatedVenda criada e enviada ao terminal; aguardando o portadorMostrar “insira/aproxime o cartão”
approvedPagamento aprovadoConcluir a venda; o webhook de pagamento chega em seguida
declinedPagamento recusadoOferecer nova tentativa (nova Idempotency-Key)
abortedCancelada antes de pagar (operador/portador desistiu)Encerrar sem cobrança
unknownNão sabemos o resultado ainda — timeout ou quedaConsultar até resolver; nunca reenviar cego
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} 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.

​
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.
ReversoEvento que você recebeEstado final
Cancelamentopayment.canceledcanceled
Reembolso totalpayment.refundedrefunded
Reembolso parcialpayment.refundedrefunded_partially
Contestação (chargeback)payment.chargeback_requestedchargeback
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.

​
Checklist de “estou pronto”

Recebo payment.created e payment.authorized e reconheço a venda de maquininha pelo bloco pos.
Dedupliquei pelo uuid da venda e pelo ID do evento.
Confirmo o estado com GET /payments/{identifier} antes de agir sobre dinheiro/estoque.
Concilio pelo pos.terminal.code.
Trato reembolso, cancelamento e chargeback.
No modo ativo, envio Idempotency-Key e trato o estado unknown (consultar, nunca reenviar cego).
Referência da API: Criar Venda no Terminal · Consultar Venda no Terminal · Webhook de Venda no Terminal.