Cobranças e saques PIX, por HTTP

curl -X POST https://keropay.co/api/cashin \
  -H "Content-Type: application/json" \
  -H "X-Client-Id: SEU_CLIENT_ID" \
  -H "X-Client-Secret: SEU_CLIENT_SECRET" \
  -d '{
    "amount": 123.45,
    "name": "Cliente Pix",
    "document": "12345678900",
    "description": "Pedido #123",
    "webhook_url": "https://seusistema.com/webhooks/keropay",
    "splits": [ { "username": "usuario1", "percentage": 10 } ]
  }'

<?php
$ch = curl_init('https://keropay.co/api/cashin');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'X-Client-Id: '     . getenv('VP_CLIENT_ID'),
        'X-Client-Secret: ' . getenv('VP_CLIENT_SECRET'),
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        'amount'      => 123.45,
        'name'        => 'Cliente Pix',
        'document'    => '12345678900',
        'description' => 'Pedido #123',
        'webhook_url' => 'https://seusistema.com/webhooks/keropay',
    ]),
]);
$body = curl_exec($ch);
curl_close($ch);

$res = json_decode($body, true);

// Decide pelo campo "ok". O status HTTP e 200 tambem no erro.
if (empty($res['ok'])) {
    throw new RuntimeException($res['error'] ?? 'Falha ao gerar PIX');
}

$copiaECola    = $res['copyPaste'];       // mostre ao pagador
$requestNumber = $res['request_number'];  // guarde: e a chave da consulta

const res = await fetch('https://keropay.co/api/cashin', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Client-Id': process.env.VP_CLIENT_ID,
    'X-Client-Secret': process.env.VP_CLIENT_SECRET,
  },
  body: JSON.stringify({
    amount: 123.45,
    name: 'Cliente Pix',
    document: '12345678900',
    description: 'Pedido #123',
    webhook_url: 'https://seusistema.com/webhooks/keropay',
  }),
});

// Nao use res.ok nem res.status: o status e 200 mesmo quando a operacao falha.
const data = await res.json();
if (!data.ok) throw new Error(data.error);

const copiaECola    = data.copyPaste;       // mostre ao pagador
const requestNumber = data.request_number;  // guarde: e a chave da consulta

import os
import requests

r = requests.post(
    "https://keropay.co/api/cashin",
    headers={
        "X-Client-Id": os.environ["VP_CLIENT_ID"],
        "X-Client-Secret": os.environ["VP_CLIENT_SECRET"],
    },
    json={
        "amount": 123.45,
        "name": "Cliente Pix",
        "document": "12345678900",
        "description": "Pedido #123",
        "webhook_url": "https://seusistema.com/webhooks/keropay",
    },
    timeout=30,
)

# Sem r.raise_for_status(): ele nunca dispara aqui e faria todo erro passar.
data = r.json()
if not data.get("ok"):
    raise RuntimeError(data.get("error", "Falha ao gerar PIX"))

copia_e_cola   = data["copyPaste"]       # mostre ao pagador
request_number = data["request_number"]  # guarde: e a chave da consulta

{
  "ok": true,
  "status": "pending",
  "amount": 123.45,
  "request_number": "veo_...",
  "transaction_id": "...",
  "copyPaste": "000201...",
  "qr_url": "https://keropay.co/api/requests?route=pix-qr&d=...&s=...",
  "qr_img": "iVBORw0KGgoAAAANSUhEUg...",
  "checkout_url": "",
  "expire_minutes": 30,

  "qr": "000201...",
  "copy_paste": "000201...",
  "code": "000201...",
  "pix_code": "000201...",
  "pix_qr_base64": "iVBORw0KGgoAAAANSUhEUg...",
  "transaction": "..."
}

{
  "amount": 150.00,
  "payment_method": "boleto",
  "name": "Maria Souza",
  "email": "[email protected]",
  "document": "12345678909",
  "phone": "11987654321",
  "address": { "zip_code": "01310100", "street": "Avenida Paulista", "number": "1000",
               "complement": "", "neighborhood": "Bela Vista", "city": "São Paulo", "state": "SP" },
  "webhook_url": "https://seusistema.com/webhooks/keropay"
}

{
  "amount": 297.00,
  "payment_method": "credit_card",
  "name": "Maria Souza",
  "email": "[email protected]",
  "webhook_url": "https://seusistema.com/webhooks/keropay"
}

{
  "ok": true,
  "status": "pending",
  "amount": 150.00,
  "request_number": "pgm_...",
  "transaction_id": "or_...",
  "copyPaste": "",
  "qr_url": "",
  "qr_img": "",
  "checkout_url": "https://keropay.co/pagamento/pgm_...",
  "expire_minutes": 8640,
  "fee": 3.49,
  "payment_method": "boleto",
  "boleto": {
    "line": "23793381286000000000300000000400184340000015000",
    "line_formatted": "23793.38128 60000.000003 00000.000400 1 84340000015000",
    "barcode": "23791843400000150003381260000000000000000040",
    "due_date": "2026-10-25",
    "url": "https://keropay.co/pagamento/pgm_..."
  }
}

{
  "ok": true,
  "status": "pending",
  "amount": 297.00,
  "request_number": "pgm_...",
  "transaction_id": "pgm_...",
  "copyPaste": "",
  "qr_url": "",
  "qr_img": "",
  "checkout_url": "https://keropay.co/pagamento/pgm_...",
  "expire_minutes": 1440,
  "fee": 14.82,
  "payment_method": "credit_card",
  "card": { "payment_url": "https://keropay.co/pagamento/pgm_...", "installments": null, "buyer_interest": 0 }
}

curl -X POST https://keropay.co/api/cashout \
  -H "Content-Type: application/json" \
  -H "X-Client-Id: SEU_CLIENT_ID" \
  -H "X-Client-Secret: SEU_CLIENT_SECRET" \
  -H "Idempotency-Key: pedido-9f3c1a-saque-01" \
  -d '{
    "amount": 250.00,
    "name": "Fulano de Tal",
    "document": "00000000000",
    "pix_key": "[email protected]",
    "pix_type": "EMAIL",
    "webhook_url": "https://seusistema.com/webhooks/keropay"
  }'

<?php
// A Idempotency-Key e NOVA a cada pedido distinto, e a MESMA no retry do
// mesmo pedido. E a unica protecao contra pagar duas vezes depois de 30s.
$idem = 'saque-' . $pedidoId;

$ch = curl_init('https://keropay.co/api/cashout');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 40,
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'X-Client-Id: '     . getenv('VP_CLIENT_ID'),
        'X-Client-Secret: ' . getenv('VP_CLIENT_SECRET'),
        'Idempotency-Key: ' . $idem,
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        'amount'      => 250.00,
        'name'        => 'Fulano de Tal',
        'document'    => '00000000000',  // mande como veio: nao remova letras
        'pix_key'     => '[email protected]',
        'pix_type'    => 'EMAIL',
        'webhook_url' => 'https://seusistema.com/webhooks/keropay',
    ]),
]);
$res = json_decode(curl_exec($ch), true);
curl_close($ch);

if (empty($res['ok'])) {
    throw new RuntimeException($res['error'] ?? 'Falha ao criar saque');
}

// "idempotent" => este saque JA EXISTIA. Nao some ao seu total, nao crie outro.
$jaExistia = !empty($res['idempotent']);
$e2e       = $res['e2e'];  // guarde: e por ele que o webhook casa com o saque

// A Idempotency-Key e NOVA a cada pedido distinto, e a MESMA no retry do
// mesmo pedido. E a unica protecao contra pagar duas vezes depois de 30s.
const idem = `saque-${pedidoId}`;

const res = await fetch('https://keropay.co/api/cashout', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Client-Id': process.env.VP_CLIENT_ID,
    'X-Client-Secret': process.env.VP_CLIENT_SECRET,
    'Idempotency-Key': idem,
  },
  body: JSON.stringify({
    amount: 250.0,
    name: 'Fulano de Tal',
    document: '00000000000', // mande como veio: nao remova letras
    pix_key: '[email protected]',
    pix_type: 'EMAIL',
    webhook_url: 'https://seusistema.com/webhooks/keropay',
  }),
});

const data = await res.json();
if (!data.ok) throw new Error(data.error);

// "idempotent" => este saque JA EXISTIA. Nao some ao seu total, nao crie outro.
const jaExistia = Boolean(data.idempotent);
const e2e = data.e2e; // guarde: e por ele que o webhook casa com o saque

import os
import requests

# A Idempotency-Key e NOVA a cada pedido distinto, e a MESMA no retry do
# mesmo pedido. E a unica protecao contra pagar duas vezes depois de 30s.
idem = f"saque-{pedido_id}"

r = requests.post(
    "https://keropay.co/api/cashout",
    headers={
        "X-Client-Id": os.environ["VP_CLIENT_ID"],
        "X-Client-Secret": os.environ["VP_CLIENT_SECRET"],
        "Idempotency-Key": idem,
    },
    json={
        "amount": 250.00,
        "name": "Fulano de Tal",
        "document": "00000000000",  # mande como veio: nao remova letras
        "pix_key": "[email protected]",
        "pix_type": "EMAIL",
        "webhook_url": "https://seusistema.com/webhooks/keropay",
    },
    timeout=40,
)

data = r.json()
if not data.get("ok"):
    raise RuntimeError(data.get("error", "Falha ao criar saque"))

# "idempotent" => este saque JA EXISTIA. Nao some ao seu total, nao crie outro.
ja_existia = bool(data.get("idempotent"))
e2e = data["e2e"]  # guarde: e por ele que o webhook casa com o saque

{
  "ok": true,
  "e2e": "WD_...",
  "fee": 2.5,
  "status": "pending",
  "auto": false
}

curl -X GET "https://keropay.co/api/consult-transaction?request_number=veo_abc123" \
  -H "X-Client-Id: SEU_CLIENT_ID" \
  -H "X-Client-Secret: SEU_CLIENT_SECRET"

<?php
$url = 'https://keropay.co/api/consult-transaction?request_number=' . urlencode($requestNumber);

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 15,
    CURLOPT_HTTPHEADER     => [
        'X-Client-Id: '     . getenv('VP_CLIENT_ID'),
        'X-Client-Secret: ' . getenv('VP_CLIENT_SECRET'),
    ],
]);
$res = json_decode(curl_exec($ch), true);
curl_close($ch);

if (empty($res['ok'])) {
    throw new RuntimeException($res['error'] ?? 'Falha ao consultar');
}

// So "confirmed" libera o pedido. Qualquer outro valor, inclusive um que
// voce nao conheca, e tratado como NAO PAGO.
if ($res['status'] === 'confirmed') {
    liberarPedido($requestNumber);
}

const url = `https://keropay.co/api/consult-transaction?request_number=${encodeURIComponent(requestNumber)}`;

const res = await fetch(url, {
  headers: {
    'X-Client-Id': process.env.VP_CLIENT_ID,
    'X-Client-Secret': process.env.VP_CLIENT_SECRET,
  },
});

const data = await res.json();
if (!data.ok) throw new Error(data.error);

// So "confirmed" libera o pedido. Qualquer outro valor, inclusive um que
// voce nao conheca, e tratado como NAO PAGO.
if (data.status === 'confirmed') {
  await liberarPedido(requestNumber);
}

import os
import requests

r = requests.get(
    "https://keropay.co/api/consult-transaction",
    params={"request_number": request_number},
    headers={
        "X-Client-Id": os.environ["VP_CLIENT_ID"],
        "X-Client-Secret": os.environ["VP_CLIENT_SECRET"],
    },
    timeout=15,
)

data = r.json()
if not data.get("ok"):
    raise RuntimeError(data.get("error", "Falha ao consultar"))

# So "confirmed" libera o pedido. Qualquer outro valor, inclusive um que
# voce nao conheca, e tratado como NAO PAGO.
if data["status"] == "confirmed":
    liberar_pedido(request_number)

{
  "ok": true,
  "type": "cashin",
  "status": "pending",
  "amount": 123.45,
  "fee": 1.23,
  "request_number": "veo_...",
  "transaction_id": "...",
  "e2e": "...",
  "updated_at": "2025-11-24 12:00:00",
  "expire_minutes": 30,
  "remaining": 27
}

curl -X GET https://keropay.co/api/balance \
  -H "X-Client-Id: SEU_CLIENT_ID" \
  -H "X-Client-Secret: SEU_CLIENT_SECRET"

<?php
$ch = curl_init('https://keropay.co/api/balance');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 15,
    CURLOPT_HTTPHEADER     => [
        'X-Client-Id: '     . getenv('VP_CLIENT_ID'),
        'X-Client-Secret: ' . getenv('VP_CLIENT_SECRET'),
    ],
]);
$res = json_decode(curl_exec($ch), true);
curl_close($ch);

if (empty($res['ok'])) {
    throw new RuntimeException($res['error'] ?? 'Falha ao consultar saldo');
}

$disponivel = $res['balance']['available'];  // e contra este numero que o saque decide
$bloqueado  = $res['balance']['blocked'];    // retido por disputa: nao saca

const res = await fetch('https://keropay.co/api/balance', {
  headers: {
    'X-Client-Id': process.env.VP_CLIENT_ID,
    'X-Client-Secret': process.env.VP_CLIENT_SECRET,
  },
});

const data = await res.json();
if (!data.ok) throw new Error(data.error);

const disponivel = data.balance.available; // e contra este numero que o saque decide
const bloqueado = data.balance.blocked;    // retido por disputa: nao saca

import os
import requests

r = requests.get(
    "https://keropay.co/api/balance",
    headers={
        "X-Client-Id": os.environ["VP_CLIENT_ID"],
        "X-Client-Secret": os.environ["VP_CLIENT_SECRET"],
    },
    timeout=15,
)

data = r.json()
if not data.get("ok"):
    raise RuntimeError(data.get("error", "Falha ao consultar saldo"))

disponivel = data["balance"]["available"]  # e contra este numero que o saque decide
bloqueado = data["balance"]["blocked"]     # retido por disputa: nao saca

{
  "ok": true,
  "balance": {
    "available": 1520.40,
    "blocked": 300.00,
    "total": 1820.40,
    "currency": "BRL"
  },
  "updated_at": "2026-08-04 10:32:11"
}

curl -X POST https://keropay.co/api/transfer \
  -H "Content-Type: application/json" \
  -H "X-Client-Id: SEU_CLIENT_ID" \
  -H "X-Client-Secret: SEU_CLIENT_SECRET" \
  -d '{
    "to": "loja_parceira",
    "amount": 250.00,
    "external_id": "repasse-2026-08-04-0031",
    "description": "Repasse semanal"
  }'

<?php
// external_id: o MESMO no retry, DIFERENTE em cada repasse legitimo.
// Sem ele a protecao cai para 15 segundos por (destino + valor).
$ch = curl_init('https://keropay.co/api/transfer');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'X-Client-Id: '     . getenv('VP_CLIENT_ID'),
        'X-Client-Secret: ' . getenv('VP_CLIENT_SECRET'),
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        'to'          => 'loja_parceira',
        'amount'      => 250.00,
        'external_id' => 'repasse-' . $repasseId,  // max. 64 caracteres
        'description' => 'Repasse semanal',
    ]),
]);
$res = json_decode(curl_exec($ch), true);
curl_close($ch);

if (empty($res['ok'])) {
    // NAO retente automaticamente 404 (destinatario) nem 400 (saldo):
    // os dois so passam se o caller corrigir algo.
    throw new RuntimeException($res['error'] ?? 'Falha ao transferir');
}

// "deduplicated" => e a transferencia JA EXISTENTE, devolvida de novo.
if (empty($res['deduplicated'])) {
    registrarRepasse($res['e2e'], $res['amount']);
}

// external_id: o MESMO no retry, DIFERENTE em cada repasse legitimo.
// Sem ele a protecao cai para 15 segundos por (destino + valor).
const res = await fetch('https://keropay.co/api/transfer', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Client-Id': process.env.VP_CLIENT_ID,
    'X-Client-Secret': process.env.VP_CLIENT_SECRET,
  },
  body: JSON.stringify({
    to: 'loja_parceira',
    amount: 250.0,
    external_id: `repasse-${repasseId}`, // max. 64 caracteres
    description: 'Repasse semanal',
  }),
});

const data = await res.json();
if (!data.ok) {
  // NAO retente automaticamente 404 (destinatario) nem 400 (saldo):
  // os dois so passam se o caller corrigir algo.
  throw new Error(data.error);
}

// "deduplicated" => e a transferencia JA EXISTENTE, devolvida de novo.
if (!data.deduplicated) {
  await registrarRepasse(data.e2e, data.amount);
}

import os
import requests

# external_id: o MESMO no retry, DIFERENTE em cada repasse legitimo.
# Sem ele a protecao cai para 15 segundos por (destino + valor).
r = requests.post(
    "https://keropay.co/api/transfer",
    headers={
        "X-Client-Id": os.environ["VP_CLIENT_ID"],
        "X-Client-Secret": os.environ["VP_CLIENT_SECRET"],
    },
    json={
        "to": "loja_parceira",
        "amount": 250.00,
        "external_id": f"repasse-{repasse_id}",  # max. 64 caracteres
        "description": "Repasse semanal",
    },
    timeout=30,
)

data = r.json()
if not data.get("ok"):
    # NAO retente automaticamente 404 (destinatario) nem 400 (saldo):
    # os dois so passam se o caller corrigir algo.
    raise RuntimeError(data.get("error", "Falha ao transferir"))

# "deduplicated" => e a transferencia JA EXISTENTE, devolvida de novo.
if not data.get("deduplicated"):
    registrar_repasse(data["e2e"], data["amount"])

{
  "ok": true,
  "status": "completed",
  "e2e": "T20260804103211A1B2C3D4E5F6",
  "amount": 250.00,
  "to_account": 482,
  "to": "loja_parceira",
  "external_id": "repasse-2026-08-04-0031"
}

<?php
// Handler de webhook. Recebe cashin e cashout na MESMA URL: separe por "type".

// 1) ASSINATURA primeiro, sobre o corpo BRUTO (nunca sobre o JSON reserializado).
//    SEGREDO_WEBHOOK = "Segredo do webhook" da chave, em Dashboard > API.
$corpo = file_get_contents('php://input');
if (!assinaturaValida($_SERVER['HTTP_X_KERO_SIGNATURE'] ?? '', $corpo, SEGREDO_WEBHOOK)) {
    http_response_code(401);   // nao veio de nos: descarte sem processar
    exit;
}
$evt = json_decode($corpo, true) ?: [];

// Responde 200 SEMPRE, e ANTES de processar. Um 500 faz o evento voltar e
// repetir o mesmo problema; passar de 10s tambem faz o envio desistir, e
// consultarStatus(), la embaixo, e uma chamada HTTP.
http_response_code(200);
if (function_exists('fastcgi_finish_request')) { fastcgi_finish_request(); }

// Fora do PHP-FPM a resposta so sai no fim, entao ainda e preciso garantir o
// 200: o exception handler pega exception E Error (PHP 7+) e deixa o script
// terminar em silencio, em vez de virar pagina de erro com status 500: o
// register_shutdown_function sozinho nao resolve, porque quando o erro ja
// imprimiu alguma coisa os cabecalhos ja foram.
set_exception_handler(function ($e) { error_log('webhook: ' . $e->getMessage()); });
register_shutdown_function(function () { if (!headers_sent()) { http_response_code(200); } });

$type   = $evt['type']   ?? '';
$status = $evt['status'] ?? '';
$chave  = $type === 'cashout' ? ($evt['e2e'] ?? '') : ($evt['request_number'] ?? '');

if ($chave === '' || jaProcessado($type, $chave, $status)) {
    exit;  // idempotencia: mesmo evento duas vezes nao processa duas vezes
}
marcarProcessado($type, $chave, $status);

if ($type === 'cashin') {
    switch ($status) {
        case 'confirmed':
            // Assinatura ja conferida. Consultar o status e uma segunda
            // conferencia, barata, antes de liberar valor.
            if (consultarStatus($chave) === 'confirmed') {
                liberarPedido($chave);
            }
            break;

        case 'contested':
        case 'chargedback':
        case 'refunded':
            // Chegam DEPOIS de "confirmed": o dinheiro saiu do seu saldo.
            reverterPedido($chave, $status);
            break;

        case 'canceled':
        case 'expired':
            // expired ainda pode virar confirmed (pagamento no ultimo instante,
            // confirmado depois do prazo): cancele de um jeito que o case
            // 'confirmed' consiga reabrir e liberar.
            cancelarPedido($chave);
            break;

        default:
            // pending e qualquer status novo: NAO PAGO. Registre e siga.
            registrarStatusDesconhecido($chave, $status);
    }
} elseif ($type === 'cashout') {
    switch ($status) {
        case 'completed': marcarSaquePago($chave);       break;
        case 'canceled':  devolverSaqueAoSaldo($chave);  break;  // valor + taxa voltaram
        default:          registrarSaquePendente($chave, $status);
    }
}

function assinaturaValida(string $hdr, string $corpo, string $segredo): bool
{
    if (!preg_match('/^t=(\d+),v1=([a-f0-9]{64})$/', $hdr, $m)) { return false; }
    if (abs(time() - (int)$m[1]) > 300) { return false; }   // mais de 5 min: replay
    return hash_equals($m[2], hash_hmac('sha256', $m[1] . '.' . $corpo, $segredo));
}

// Handler de webhook (Express). Recebe cashin e cashout na MESMA URL.
// express.raw, e NAO express.json: a assinatura e sobre os bytes exatos.
const crypto = require('crypto');

app.post('/webhooks/pix', express.raw({ type: 'application/json' }), async (req, res) => {
  // 1) Assinatura primeiro. KERO_WEBHOOK_SECRET = "Segredo do webhook" da chave.
  if (!assinaturaValida(req.get('X-Kero-Signature') || '', req.body, process.env.KERO_WEBHOOK_SECRET)) {
    return res.sendStatus(401);  // nao veio de nos: descarte
  }
  // Responde 200 ANTES de processar. Um 500 faz o evento voltar e repetir
  // o mesmo problema, sem nunca sair do lugar.
  res.sendStatus(200);

  let evt = {};
  try { evt = JSON.parse(req.body.toString('utf8')); } catch (e) { return; }
  const { type, status } = evt;
  const chave = type === 'cashout' ? evt.e2e : evt.request_number;

  try {
    // A idempotencia fica DENTRO do try: ja respondemos 200, entao a promise
    // nao tem quem a espere. Uma rejeicao aqui fora vira unhandled rejection,
    // e no Node moderno isso DERRUBA o processo, levando junto os outros
    // webhooks em voo.
    if (!chave || (await jaProcessado(type, chave, status))) return;
    await marcarProcessado(type, chave, status);

    if (type === 'cashin') {
      switch (status) {
        case 'confirmed':
          // Assinatura ja conferida. Consultar o status e uma segunda
          // conferencia, barata, antes de liberar valor.
          if ((await consultarStatus(chave)) === 'confirmed') {
            await liberarPedido(chave);
          }
          break;

        case 'contested':
        case 'chargedback':
        case 'refunded':
          // Chegam DEPOIS de "confirmed": o dinheiro saiu do seu saldo.
          await reverterPedido(chave, status);
          break;

        case 'canceled':
        case 'expired':
          // expired ainda pode virar confirmed (pagamento no ultimo instante,
          // confirmado depois do prazo): cancele de um jeito que o case
          // 'confirmed' consiga reabrir e liberar.
          await cancelarPedido(chave);
          break;

        default:
          // pending e qualquer status novo: NAO PAGO. Registre e siga.
          await registrarStatusDesconhecido(chave, status);
      }
    } else if (type === 'cashout') {
      if (status === 'completed') await marcarSaquePago(chave);
      else if (status === 'canceled') await devolverSaqueAoSaldo(chave);
      else await registrarSaquePendente(chave, status);
    }
  } catch (err) {
    // Ja respondemos 200; so registre para investigar depois.
    console.error('webhook', chave, err);
  }
});

function assinaturaValida(hdr, corpo, segredo) {
  const m = /^t=(\d+),v1=([a-f0-9]{64})$/.exec(hdr);
  if (!m || !segredo || Math.abs(Date.now() / 1000 - Number(m[1])) > 300) return false;
  const esperado = crypto.createHmac('sha256', segredo).update(m[1] + '.').update(corpo).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(esperado), Buffer.from(m[2]));
}

# Handler de webhook (Flask). Recebe cashin e cashout na MESMA URL.
# from threading import Thread
@app.post("/webhooks/pix")
def webhook_pix():
    # Responde 200 ANTES de processar: o timeout do envio e de 10s, e
    # consultar_status() la embaixo e uma chamada HTTP. O evento vai POR VALOR
    # para a thread: `request` nao existe fora do contexto do Flask.
    # Em producao, troque a Thread por uma fila de verdade (Celery, RQ): o
    # processo pode reiniciar no meio e a thread morre sem deixar rastro.
    # 1) Assinatura primeiro, sobre os bytes brutos (antes de get_json).
    corpo = request.get_data()
    if not assinatura_valida(request.headers.get("X-Kero-Signature", ""), corpo, SEGREDO_WEBHOOK):
        return "", 401  # nao veio de nos: descarte
    evt = request.get_json(silent=True) or {}
    Thread(target=processar_evento, args=(evt,), daemon=True).start()
    return "", 200


def processar_evento(evt):
    tipo = evt.get("type", "")
    status = evt.get("status", "")
    chave = evt.get("e2e") if tipo == "cashout" else evt.get("request_number")

    try:
        if not chave or ja_processado(tipo, chave, status):
            return  # idempotencia

        marcar_processado(tipo, chave, status)

        if tipo == "cashin":
            if status == "confirmed":
                # Assinatura ja conferida. Consultar o status e uma segunda
                # conferencia, barata, antes de liberar valor.
                if consultar_status(chave) == "confirmed":
                    liberar_pedido(chave)

            elif status in ("contested", "chargedback", "refunded"):
                # Chegam DEPOIS de "confirmed": o dinheiro saiu do seu saldo.
                reverter_pedido(chave, status)

            elif status in ("canceled", "expired"):
                # expired ainda pode virar confirmed (pagamento no ultimo instante,
                # confirmado depois do prazo): cancele de um jeito que o ramo
                # "confirmed" consiga reabrir e liberar.
                cancelar_pedido(chave)

            else:
                # pending e qualquer status novo: NAO PAGO. Registre e siga.
                registrar_status_desconhecido(chave, status)

        elif tipo == "cashout":
            if status == "completed":
                marcar_saque_pago(chave)
            elif status == "canceled":
                devolver_saque_ao_saldo(chave)  # valor + taxa voltaram
            else:
                registrar_saque_pendente(chave, status)

    except Exception:
        # Ja respondemos 200; so registre para investigar depois.
        app.logger.exception("webhook %s", chave)


# import hmac, hashlib, re, time
def assinatura_valida(hdr, corpo, segredo):
    m = re.fullmatch(r"t=(\d+),v1=([a-f0-9]{64})", hdr or "")
    if not m or not segredo or abs(time.time() - int(m.group(1))) > 300:
        return False
    esperado = hmac.new(segredo.encode(), m.group(1).encode() + b"." + corpo, hashlib.sha256).hexdigest()
    return hmac.compare_digest(esperado, m.group(2))

{ "ok": false, "error": "Mensagem do erro" }

<?php
// O unico jeito correto de ler uma resposta desta API.
$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HEADER         => true,   // precisamos do X-App-Error-Code
    CURLOPT_TIMEOUT        => 30,
    /* ... */
]);
$raw     = curl_exec($ch);
$hdrSize = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
curl_close($ch);

$headers = substr($raw, 0, $hdrSize);
$res     = json_decode(substr($raw, $hdrSize), true) ?: [];

// NAO cheque o status HTTP. Cheque "ok".
if (empty($res['ok'])) {
    preg_match('/^X-App-Error-Code:\s*(\d+)/mi', $headers, $m);
    $code = (int)($m[1] ?? 0);

    // 429 e transitorio (limitador); 5xx tambem. O resto so passa se o
    // caller corrigir os dados: nao retente em loop.
    $transitorio = ($code === 429 || $code >= 500);
    throw new ApiException($res['error'] ?? 'Falha', $code, $transitorio);
}

// O unico jeito correto de ler uma resposta desta API.
const res = await fetch(url, { /* ... */ });
const data = await res.json();

// NAO use res.ok nem res.status. Cheque "ok" do corpo.
if (!data.ok) {
  const code = Number(res.headers.get('X-App-Error-Code') || res.status || 0);

  // 429 e transitorio (limitador); 5xx tambem. O resto so passa se o
  // caller corrigir os dados: nao retente em loop.
  const transitorio = code === 429 || code >= 500;
  throw new ApiError(data.error, code, transitorio);
}

# O unico jeito correto de ler uma resposta desta API.
r = requests.post(url, json=payload, timeout=30)

# Sem r.raise_for_status(): ele nunca dispara nas rotas de negocio
# e faria TODA falha passar como sucesso.
data = r.json()
if not data.get("ok"):
    code = int(r.headers.get("X-App-Error-Code") or r.status_code or 0)

    # 429 e transitorio (limitador); 5xx tambem. O resto so passa se o
    # caller corrigir os dados: nao retente em loop.
    transitorio = code == 429 or code >= 500
    raise ApiError(data.get("error", "Falha"), code, transitorio)