Integração para outros sistemas

Autenticação

Envie a chave em todas as chamadas autenticadas:

Authorization: Bearer iztec_live_SEU_TOKEN

A chave de produção fica no servidor. Não publique no frontend do cliente.

POST /api/v1/charges

Cria a cobrança no checkout iZTECPAY e devolve os dados para você mostrar PIX e cartão no seu app.

curl -X POST https://checkout.iztec.online/api/v1/charges \
  -H "Authorization: Bearer iztec_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 30.00,
    "reference": "PEDIDO-200",
    "description": "Pedido 200",
    "customer": {
      "name": "Maria Silva",
      "document": "12345678901",
      "email": "maria@email.com"
    },
    "methods": ["pix", "card"],
    "success_url": "https://seusistema.com/pedido/200/ok",
    "cancel_url": "https://seusistema.com/pedido/200/cancel"
  }'

O customer é quem paga. O recebedor é sempre Almv Softwares LTDA, CNPJ 66.504.824/0001-07.

Resposta 201:

{
  "id": "ch_...",
  "status": "pending",
  "amount": "30.00",
  "receiver": {
    "name": "Almv Softwares LTDA",
    "document": "66504824000107",
    "trade_name": "Iztec Tecnologia"
  },
  "checkout_url": "https://checkout.iztec.online/p/ch_...",
  "pix": {
    "txid": "CH...",
    "copia_e_cola": "00020126...",
    "qrcode_url": "https://checkout.iztec.online/api/v1/charges/ch_.../qrcode.png",
    "qrcode_base64": "data:image/png;base64,..."
  },
  "card": {
    "checkout_url": "https://checkout.iztec.online/p/ch_...",
    "widget_url": "https://checkout.iztec.online/api/public/card.php",
    "status_url": "https://checkout.iztec.online/api/public/status.php?id=ch_..."
  }
}

O mesmo JSON chega no webhook charge.created, sem o qrcode_base64.

Mostrar no seu checkout

1. Seu backend chama POST /api/v1/charges (a chave não vai no navegador do cliente).
2. PIX: use pix.qrcode_url ou pix.qrcode_base64 e o pix.copia_e_cola.
3. Cartão: abra checkout_url (ou iframe) — a tela já tem PIX e cartão. Para embutir o formulário, dê POST em card.widget_url com {"id":"ch_...","card_type":"credit"} e carregue o widget ACI com o checkoutId.
4. Consulte card.status_url até paid, ou espere o webhook payment.paid.

GET /api/v1/charges/{id}

Consulta status, PIX e dados da cobrança.

curl https://checkout.iztec.online/api/v1/charges/ch_... \
  -H "Authorization: Bearer iztec_live_SEU_TOKEN"

QR Code

Imagem PNG pública da cobrança (o id é opaco):

GET https://checkout.iztec.online/api/v1/charges/{id}/qrcode.png

Webhook

Enviamos POST para https://webhook.iztec.online/receive.php e gravamos no banco do inbox. Se a cobrança informar outro webhook_url, enviamos para os dois.

Eventos: charge.created, payment.paid, payment.failed.

X-IZTECPAY-Event: payment.paid
X-IZTECPAY-Signature: sha256=...

{
  "id": "evt_...",
  "event": "payment.paid",
  "created_at": "2026-08-23T11:30:00-03:00",
  "data": {
    "id": "ch_...",
    "status": "paid",
    "method": "card",
    "amount": "30.00",
    "reference": "PEDIDO-200"
  }
}

Valide a assinatura com HMAC-SHA256 do body cru e o segredo do webhook. Responda HTTP 2xx. Tentamos de novo automaticamente se falhar.

Cartão: a confirmação chega pelo retorno ACI e dispara payment.paid. PIX: o QR/copia e cola já saem na criação; o status muda para pago quando o conector ou o retorno confirmar a liquidação.