Integrator

Guias

Cobranças

Crie, acompanhe, liste e cancele cobranças. Toda cobrança vai para um terminal específico e passa por estados bem definidos.

Criar uma cobrança

POST/v1/charges

Corpo (JSON)

terminal_iduuidobrigatório
O id do terminal que deve cobrar. Veja os terminais em GET /v1/terminals.
amountinteiroobrigatório
Valor em centavos, de 1 a 10000000 (R$ 100.000,00).
methodstringobrigatório
credit (crédito à vista), debit ou pix.
descriptionstring
Até 140 caracteres. Aparece na maquininha e no painel.
external_referencestring
Até 100 caracteres. Seu identificador (pedido, comanda). Volta no webhook e pode ser usado como filtro.

Cabeçalhos

Authorizationstringobrigatório
Bearer itg_live_…
Idempotency-Keystring
Recomendado. Até 255 caracteres. Garante que um retry não crie outra cobrança. Veja Idempotência.
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"
  }'

Resposta 201 Created com o objeto cobrança em pending. Se a mesma Idempotency-Key já foi usada com os mesmos dados, a resposta é 200 OK com a cobrança original.

Quando a criação é recusada

  • 402 insufficient_credits: o saldo atingiu o limite negativo da conta.
  • 403 account_blocked: conta bloqueada pelo suporte.
  • 404 terminal_not_found ou 409 terminal_revoked: confira o terminal_id.

Ciclo de vida

pendingna fila
→
processingna maquininha
→
approveddeclinedcanceledfailed
direto de pending:canceledexpired
pendingNa fila, esperando a maquininha buscar. Expira se não for buscada a tempo (padrão: 2 minutos).
processingA maquininha pegou a cobrança e abriu o pagamento. O cliente está pagando.
approvedPaga. Traz nsu, authorization_code, card_brand e a tarifa (fee) em créditos.
declinedRecusada pela adquirente ou emissor (saldo, senha, cartão bloqueado…).
canceledCancelada por você via API (enquanto pending) ou pelo operador na maquininha.
failedErro técnico na maquininha ou interrupção. Veja failure_reason.
expiredFicou na fila além do tempo limite sem a maquininha buscar.

approved, declined, canceled, failed e expired são finais e sempre disparam um webhook.

Motivos de falha

declined_by_acquirerdeclined
A adquirente negou. acquirer_code e failure_message trazem o motivo dela.
canceled_on_terminalcanceled
O operador cancelou na maquininha.
canceled_by_merchantcanceled
Você cancelou via API enquanto estava pending.
not_picked_upexpired
A maquininha não buscou a cobrança a tempo (desligada, sem internet ou sem o app aberto).
terminal_unavailablefailed
O app de pagamento da adquirente não está disponível no aparelho.
terminal_timeoutfailed
O pagamento não terminou em 5 minutos.
terminal_errorfailed
Erro técnico informado pelo SDK da adquirente.
interruptedfailed
O app foi fechado no meio do pagamento ou não informou o resultado em 30 minutos. Confira no extrato da adquirente: em casos raros o pagamento passou.

Cobrança interrompida que foi aprovada

Se a maquininha conseguir reportar a aprovação depois de uma cobrança virar failed com interrupted, ela muda para approved e você recebe charge.approved. Trate esse evento mesmo depois de um charge.failed.

O objeto cobrança

JSON
{
  "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"
}
feeinteiro | null
Tarifa cobrada em créditos. Preenchida só quando approved.
acquirernull
Adquirente da maquininha que processou.
nsustring | null
Número sequencial da transação na adquirente. Use para conciliar com o extrato.
authorization_codestring | null
Código de autorização do emissor.
processing_atdata | null
Quando a maquininha pegou a cobrança.
completed_atdata | null
Quando chegou a um estado final.
expires_atdata
Limite para a maquininha buscar a cobrança enquanto pending.

Consultar

GET/v1/charges/{id}
cURL
curl https://api.integrator.co26.com.br/v1/charges/0b6f0f7e-5a8f-4f1e-9a52-2b7d3c1e9d10 \
  -H "Authorization: Bearer $INTEGRATOR_API_KEY"

Listar

GET/v1/charges

Query string

limit1–100
Itens por página. Padrão 20.
cursorstring
O next_cursor da página anterior.
terminal_iduuid
Só de um terminal.
statusstring
Filtra por estado.
external_referencestring
Busca pela sua referência.
created_from / created_toISO 8601
Intervalo de criação (inclusivo).
JSON
{
  "data": [
    "…objetos cobrança, mais recentes primeiro…"
  ],
  "next_cursor": "WyIyMDI2LTEwLTEzIDE4OjIw..."
}

Cancelar

POST/v1/charges/{id}/cancel

Funciona só enquanto a cobrança está pending. Depois que a maquininha pega (processing), o cancelamento é feito pelo operador na própria maquininha. Tentar cancelar fora da fila devolve 409 charge_not_cancelable.

Estornos

O Integrator não estorna vendas aprovadas. Use o estorno da própria adquirente (na maquininha ou no portal dela) com o NSU da cobrança.
Anterior← Terminais e pareamentoPróximoWebhooks →