Integrator

Primeiros passos

Início rápido

Da conta criada até a primeira cobrança aprovada, com o resultado chegando no seu webhook.

1. Crie a conta e carregue créditos

Crie sua conta e confirme o e-mail. No painel, abra Créditos e faça uma recarga por Pix ou cartão. Os créditos caem assim que o pagamento é confirmado.

2. Crie um terminal

Em Terminais → Novo terminal, dê um nome (por exemplo, "Caixa 1") e defina um PIN de 4 a 8 dígitos. O painel mostra uma única vez o token e o QR code do terminal. Guarde o id do terminal: é ele que você usa na API.

3. Instale e pareie o app na maquininha

Instale o app Integrator na maquininha, abra e toque em Escanear QR code. Quando aparecer "Aguardando cobranças" com o status Online, está pronto. Detalhes em App da maquininha.

4. Gere uma API key

Em Integração → API keys, crie uma chave. Ela começa com itg_live_ e aparece só uma vez. Guarde em uma variável de ambiente do seu servidor:

Terminal
export INTEGRATOR_API_KEY="itg_live_..."

5. Configure o webhook

Ainda em Integração, informe a URL do seu sistema que vai receber os eventos (precisa ser HTTPS) e copie o segredo de assinatura (whsec_…). Use o botão Enviar teste para confirmar que a URL responde. Veja como validar a assinatura em Webhooks.

6. Faça a primeira cobrança

curl -X POST https://api.integrator.co26.com.br/v1/charges \
  -H "Authorization: Bearer $INTEGRATOR_API_KEY" \
  -H "Idempotency-Key: pedido-1234" \
  -H "Content-Type: application/json" \
  -d '{
    "terminal_id": "6f1c2b8e-2f4a-4c55-9a59-6a1d5b1f0c3e",
    "amount": 4590,
    "method": "credit",
    "description": "Pedido #1234",
    "external_reference": "pedido-1234"
  }'

A resposta é 201 Created com a cobrança em pending. Em até um segundo ela aparece na maquininha e passa para processing. Quando o cliente pagar, seu webhook recebe charge.approved:

JSON
{
  "id": "a3b1c0de-1111-4f00-9c3a-5e2b1d0f0a99",
  "type": "charge.approved",
  "created_at": "2026-10-13T18:20:42.120Z",
  "data": {
    "id": "0b6f0f7e-5a8f-4f1e-9a52-2b7d3c1e9d10",
    "object": "charge",
    "terminal_id": "6f1c2b8e-2f4a-4c55-9a59-6a1d5b1f0c3e",
    "amount": 4590,
    "currency": "BRL",
    "method": "credit",
    "status": "approved",
    "description": "Pedido #1234",
    "external_reference": "pedido-1234",
    "fee": 46,
    "acquirer": null,
    "nsu": "000123456",
    "authorization_code": "A1B2C3",
    "card_brand": "VISA",
    "acquirer_code": "00",
    "failure_reason": null,
    "failure_message": null,
    "created_at": "2026-10-13T18:20:11.204Z",
    "processing_at": "2026-10-13T18:20:11.851Z",
    "completed_at": "2026-10-13T18:20:42.017Z",
    "expires_at": "2026-10-13T18:22:11.204Z"
  }
}

E se o webhook ainda não estiver pronto?

Você também pode consultar a cobrança com GET /v1/charges/{id} até ela sair de pending/processing. Em produção, prefira o webhook e use a consulta só como reconciliação.

Próximos passos

Anterior← Visão geralPróximoAutenticação →