O PixMate opera de forma autônoma: o terminal cobra e o painel registra tudo, sem exigir nenhuma integração. Quando já existe um sistema — um ERP, uma agenda, um software de gestão —, uma chamada cria a cobrança e o QR Code aparece no terminal do atendimento, sem digitação do valor. Quando o banco confirma o pagamento, o seu sistema é notificado.
O PixMate não retém percentual sobre o que você recebe. Eventuais tarifas de Pix são as do seu próprio banco. O uso do terminal e do sistema é contratado por plano — fale com vendas.
Quando a ordem de serviço, a comanda ou a consulta já foi emitida no sistema, a redigitação do valor no teclado é desnecessária — e é nela que se originam o erro de digitação e a divergência no fechamento.
O seu sistema informa o terminal e o valor. O QR Code aparece na tela do atendimento imediatamente, e o cliente também pode pagar por aproximação. Não é necessário renderizar o QR Code no seu sistema nem imprimi-lo.
A baixa no seu sistema não depende do comprovante apresentado pelo cliente: assim que o valor entra na conta, o PixMate aciona o seu webhook. O evento traz o txid e o terminal em que a cobrança foi paga.
A cobrança é criada na conta bancária do estabelecimento, com as credenciais dele. O PixMate não é intermediário financeiro: integrar o seu sistema não coloca ninguém entre a venda e a conta que recebe.
Autenticação OAuth2 (client_credentials) e cobranças no vocabulário do Banco Central: txid, status, valor, pixCopiaECola. Quem já integrou o Pix de um banco reconhece os campos.
No ambiente de testes o QR Code aparece no terminal real e o pagamento é simulado por uma chamada — o seu webhook é acionado como em produção. É possível fechar o ciclo completo sem movimentação de dinheiro real.
A cobrança nomeia o terminal em que deve aparecer. Uma rede com várias recepções, caixas ou salas usa a mesma credencial e escolhe, a cada chamada, em qual tela o QR Code surge.
As credenciais são criadas pelo estabelecimento no painel, em API / Integradores, e trocadas por um token de acesso.
Uma chamada com o terminal e o valor. A resposta traz o txid, e o QR Code já está na tela do terminal quando ela chega.
Aproxima o celular do terminal ou lê o QR Code. O app do banco abre com o valor preenchido.
O terminal anuncia o pagamento e o PixMate aciona o seu webhook com o txid. A baixa ocorre sem conferência de comprovante.
O manual completo da integração, com todos os campos, códigos de erro e o passo a passo do sandbox, é enviado pela nossa equipe junto com as credenciais.
# 1. Token de acesso (OAuth2 client_credentials)
curl -X POST https://pixmate.com.br/api/pix/oauth/token \
-u "$CLIENT_ID:$CLIENT_SECRET" \
-d '{"grant_type":"client_credentials"}'
# 2. Cria a cobranca no terminal. external_id e a SUA referencia (n. do pedido)
curl -X POST https://pixmate.com.br/api/pix/v1/cob \
-H "Authorization: Bearer $TOKEN" \
-d '{"device":"38240718750005","valor":"29.90","external_id":"PEDIDO-4821"}'
# → o QR JA esta na tela do terminal quando esta resposta chega
{
"txid": "a644ba667ee0cf2c7d91d15aee10f6fd",
"status": "ATIVA",
"valor": { "original": "29.90" },
"pixCopiaECola": "00020126440014br.gov.bcb.pix...",
"device": "38240718750005",
"external_id": "PEDIDO-4821"
}
# 3. O banco confirma o pagamento → o PixMate chama o SEU webhook
# com a SUA referencia de volta — a baixa e no pedido certo, sem adivinhar
POST https://seu-sistema.com.br/webhooks/pixmate
{
"tipo": "pix.recebido",
"txid": "a644ba667ee0cf2c7d91d15aee10f6fd",
"device": "38240718750005",
"external_id": "PEDIDO-4821",
"pix": [ { "valor": "29.90", "horario": "2026-07-11T02:14:47Z" } ]
}Quando o próprio sistema já é o balcão, em vez de um valor avulso ele monta o carrinho e o envia ao terminal. O operador conclui a venda no aparelho — em Pix ou em dinheiro, com troco — e a ficha é impressa como em uma venda comum.
# Envia o carrinho para um terminal (p = preco em centavos, q = quantidade)
# external_id amarra a venda ao seu pedido, do mesmo jeito da cobranca avulsa
curl -X POST https://pixmate.com.br/api/pix/v1/pos/sales \
-H "Authorization: Bearer $TOKEN" \
-d '{"device":"38240718750005","external_id":"VENDA-77","items":[{"p":1000,"q":2},{"p":1200,"q":1}]}'
# → o carrinho aparece no terminal, no total; o operador escolhe Pix ou dinheiro
{
"status": "sent",
"device": "38240718750005",
"items": 3,
"external_id": "VENDA-77"
}O preço de cada item (em centavos) é a chave do item no cardápio do PixMate. O sistema consulta os valores válidos — assim como os terminais e as contas de recebimento — por três chamadas de leitura, sem depender do painel.
# Contas de recebimento da organizacao (o id vai no campo "conta" da cobranca)
curl https://pixmate.com.br/api/pix/v1/accounts -H "Authorization: Bearer $TOKEN"
# → [{ "id": "...", "label": "EFI Bank", "provider": "efibank", "active": true }, ...]
# Terminais da organizacao (o "device" das cobrancas e vendas)
curl https://pixmate.com.br/api/pix/v1/devices -H "Authorization: Bearer $TOKEN"
# → [{ "device": "38240718750005", "name": "Recepcao", "online": true, "pos_enabled": true }, ...]
# Cardapio do PDV (o "price_cents" e a chave que vai em "p")
curl https://pixmate.com.br/api/pix/v1/catalog -H "Authorization: Bearer $TOKEN"
# → [{ "price_cents": 1000, "valor": "10.00", "label": "Agua/Refrigerante", "print_group": "copa" }, ...]| Método | Endpoint | O que faz |
|---|---|---|
| POST | /oauth/token | Troca client_id / client_secret por um token de acesso (OAuth2 client_credentials, validade de 24 h). |
| GET | /v1/accounts | Lista as contas de recebimento da organização (para o campo conta). Sem credenciais. |
| GET | /v1/devices | Lista os terminais (para o campo device), com o status online. |
| GET | /v1/catalog | Lista o cardápio do PDV; o price_cents é a chave que vai em p. |
| POST | /v1/cob | Cria a cobrança e exibe o QR no terminal. Campos: device, valor, e os opcionais external_id, descricao, conta, webhook_url. |
| GET | /v1/cob/{txid} | Consulta o status da cobrança (ATIVA ou CONCLUIDA). |
| POST | /v1/pos/sales | Envia um carrinho de PDV ao terminal (items de {p,q} + external_id); o operador conclui a venda no aparelho. |
| GET | /v1/transactions | Lista os recebimentos (Pix e dinheiro). Filtra por external_id para localizar a venda que você iniciou. |
| PUT | /v1/webhook | Registra a URL de webhook padrão da credencial (também pode ir por cobrança, em webhook_url). |
| POST | /v1/cob/{txid}/simular-pagamento | No sandbox: dispara o pagamento e aciona o webhook, como em produção. |
O evento de webhook pix.recebido e a consulta /v1/transactions devolvem o seu external_id, então a conciliação é sempre pela sua própria referência — nunca pelo nosso identificador.
pixCopiaECola é devolvido apenas para registro do seu lado.txid e o terminal. Não é preciso ficar consultando o status, embora a consulta exista. O mesmo txid pode ser notificado mais de uma vez, então trate a baixa de forma idempotente.external_id — o número do seu pedido ou da sua guia — ao criar a cobrança ou a venda de PDV, e o PixMate o devolve no webhook e na consulta de recebimentos. A baixa é sempre no pedido certo, sem precisar casar por valor e horário. A consulta /v1/transactions ainda aceita filtrar por esse external_id.client_secret aparece uma única vez, na criação. O manual completo da integração acompanha as credenciais.Informe qual sistema você usa ou desenvolve e como o atendimento cobra hoje. A nossa equipe responde com o manual da integração e as credenciais de sandbox.