2. Receber por Pix

sequenceDiagram
  participant S as Seu sistema
  participant G as Plataforma
  participant C as Cliente
  S->>G: POST /payments/merchant/transaction/pix
  G-->>S: 201 PENDING + pix.qrcode
  S->>C: mostra QR / copia e cola
  C->>G: paga o Pix
  G-->>S: webhook transaction.paid
  S->>G: GET /payments/merchant/transaction/:subTransactionId (opcional)
  S->>G: POST /payments/transactions/:subTransactionId/refunds (se precisar devolver)
  G-->>S: webhook transaction.refunded

Passo 1 — Criar a cobrança

Chave PUBLIC (ou SECRET) com CREATE_PIX_TRANSACTION. O idempotencyKey deve ser o id do pedido no seu sistema: se você reenviar, recebe a mesma cobrança.

curl -X POST https://api.gestaotechnology.com/api/payments/merchant/transaction/pix \
  -H "X-Api-Key: <PUBLIC_KEY>" -H "Content-Type: application/json" \
  -d '{
    "amountCents": 15000,
    "description": "Pedido #8812",
    "idempotencyKey": "pedido-8812",
    "customer": {
      "name": "Maria Souza",
      "email": "[email protected]",
      "documentNumber": "12345678909",
      "documentType": "CPF"
    },
    "metadata": { "pedido": "8812" }
  }'

{
  "orderId": "0f6c1a52-8a0e-4f4c-9b8e-5d2b7c1e9a10",
  "subTransactionId": "7d3e2b91-4c55-4a8f-b1d2-93f0e6a4c7b2",
  "transactionId": "TX-8812",
  "providerTransactionId": "psp-55f1c0",
  "status": "PENDING",
  "amount": { "subtotalCents": 15000, "discountCents": 0, "totalCents": 15000, "currency": "BRL" },
  "pix": {
    "qrcode": "00020126580014br.gov.bcb.pix…6304A1B2",
    "expiresAt": "2026-10-16T13:00:00.000Z"
  }
}

Guarde o subTransactionId: é o id que aparece no webhook, na consulta e no reembolso. Mostre pix.qrcode como QR Code e como copia e cola.

Passo 2 — Cliente paga → webhook `transaction.paid`

{
  "event": "transaction.paid",
  "occurredAt": "2026-10-15T13:05:12.000Z",
  "data": {
    "companyId": "c1d2e3f4-0000-4000-8000-000000000001",
    "transactionId": "TX-8812",
    "subTransactionId": "7d3e2b91-4c55-4a8f-b1d2-93f0e6a4c7b2",
    "providerTransactionId": "psp-55f1c0",
    "paymentMethod": "PIX",
    "integration": "API_DIRECT",
    "status": "PAID",
    "amount": 15000,
    "currency": "BRL"
  }
}

Ao receber: valide a assinatura, localize o pedido pelo subTransactionId, marque como pago se ainda não estiver (o evento pode repetir) e responda 200.

Passo 3 — Consultar (reserva do webhook)

Se o webhook não chegou e o cliente diz que pagou, consulte:

curl -s https://api.gestaotechnology.com/api/payments/merchant/transaction/7d3e2b91-4c55-4a8f-b1d2-93f0e6a4c7b2 \
  -H "X-Api-Key: <PUBLIC_KEY>"

{
  "subTransactionId": "7d3e2b91-4c55-4a8f-b1d2-93f0e6a4c7b2",
  "transactionId": "TX-8812",
  "providerTransactionId": "psp-55f1c0",
  "status": "PAID",
  "paidAt": "2026-10-15T13:05:11.000Z",
  "amount": { "totalCents": 15000, "refundedCents": 0, "currency": "BRL" }
}

Passo 4 — Reembolsar (opcional)

Chave SECRET com CREATE_REFUND e header Idempotency-Key (obrigatório). Sem amountCents, devolve todo o disponível.

curl -X POST https://api.gestaotechnology.com/api/payments/transactions/7d3e2b91-4c55-4a8f-b1d2-93f0e6a4c7b2/refunds \
  -H "X-Api-Key: <SECRET_KEY>" -H "Content-Type: application/json" \
  -H "Idempotency-Key: reembolso-8812-1" \
  -d '{ "amountCents": 5000, "reason": "Item fora de estoque" }'

{ "refundId": "b8a4f2c6-1e3d-4f5a-9c7b-2d6e8f0a1b3c", "status": "PROCESSING", "amountCents": 5000 }

O resultado chega por webhook:

{
  "event": "transaction.refunded",
  "occurredAt": "2026-10-15T13:20:40.000Z",
  "data": {
    "companyId": "c1d2e3f4-0000-4000-8000-000000000001",
    "refundId": "b8a4f2c6-1e3d-4f5a-9c7b-2d6e8f0a1b3c",
    "subTransactionId": "7d3e2b91-4c55-4a8f-b1d2-93f0e6a4c7b2",
    "transactionId": "TX-8812",
    "refundStatus": "COMPLETED",
    "amount": 5000,
    "currency": "BRL"
  }
}

Consulta a qualquer momento: GET /refunds/b8a4f2c6-1e3d-4f5a-9c7b-2d6e8f0a1b3c. Em reembolso parcial, transactionStatus não vem; em total, vem REFUNDED.

Erros comuns

Situação	Resposta	O que fazer
Campo faltando ou extra no corpo	`400`	Corrija o corpo; campos desconhecidos são recusados.
Reenvio com o mesmo `idempotencyKey`	`201` com a mesma cobrança	Normal: nada é duplicado.
Reembolso sem `Idempotency-Key`	`400`	Envie o header.
Chave sem o scope	`403`	Ajuste os scopes da chave no painel.

Referência: Pagamentos Pix, Reembolsos, Payloads.