Skip to main content
Toda venda presencial — seja iniciada na maquininha (o operador passa o cartão) ou pela sua aplicação (criando a venda) — chega a você pelos mesmos eventos de webhook de uma venda comum, acrescidos de um bloco pos que identifica o terminal. Esta página é a referência desse payload. Para configurar a entrega e assinar eventos, veja Configuração de Webhooks.

​
Como reconhecer uma venda presencial

A venda de maquininha se reconhece pela presença do bloco pos no payload. Venda online não tem esse bloco; o resto do payload é idêntico.
Uma venda presencial dispara os eventos normais de pagamento — no fluxo feliz, payment.created seguido de payment.authorized.

​
O bloco pos

​
pos.terminal.code
string
Código do terminal onde a venda aconteceu. É a chave para conciliar a venda com o aparelho e com o ponto de venda.
​
pos.terminal.serial_number
string
Número de série do aparelho.
​
pos.terminal.model
string
Modelo do aparelho.

​
Exemplo de payload

{
  "event": "payment.authorized",
  "data": {
    "uuid": "AUTOCC01KW2P8M4Q7K3M9QP",
    "status": "authorized",
    "amount": 5200,
    "external_reference": "PEDIDO-8842",
    "payment": {
      "payment_method": "credit_card",
      "installments": 3
    },
    "pos": {
      "terminal": {
        "code": "POI0X9Q2T7K",
        "serial_number": "S123456",
        "model": "AMS1"
      }
    }
  }
}

​
Divisão da venda (split)

Uma venda presencial dividida entre franqueadora e o recebedor dono do terminal traz também o bloco split no mesmo payload — a divisão realizada, no centavo. O terminal é o canal que determinou a regra: concilie amarrando pos.terminal.code (o aparelho) às fatias em split.
O split do POS é o mesmo bloco de qualquer venda — contrato único. Campos e exemplo em Split de Pagamento → Split realizado no retorno.

​
Eventos de reverso

Cancelamento, reembolso e contestação de uma venda presencial chegam pelos mesmos eventos de reverso de qualquer venda. A origem presencial continua reconhecível pelo bloco pos no payload.
ReversoEventoEstado final
Cancelamentopayment.canceledcanceled
Reembolso totalpayment.refundedrefunded
Reembolso parcialpayment.refundedrefunded_partially
Contestação (chargeback)payment.chargeback_requestedchargeback
Um reembolso pode chegar iniciado pelo próprio terminal (o operador estorna no aparelho), sem você ter pedido — a Autorizou registra e te avisa do mesmo jeito. Concilie pelo pos.terminal.code.

​
O webhook é um gatilho, não a verdade final

A ordem de entrega dos webhooks não é garantida e duplicatas são possíveis. Trate cada notificação como um gatilho: deduplique pelo uuid da venda e confirme o estado real com GET /payments/{identifier} antes de agir sobre dinheiro ou estoque.