Verificação de Status Unificado

O endpoint de Status Unificado é projetado especialmente para rotinas de polling no front-end e em bots (Discord, WhatsApp, Telegram), retornando o status da transação em menos de 10 milissegundos.

Por que usar o Status Unificado em vez do endpoint completo de cobrança?Ao contrário de GET /v1/charges/:id, o Status Unificado retorna um payload ultraleve (apenas id e status), consumindo o mínimo de banda de rede e consultando caches de alta velocidade.

Como Funciona

Você pode passar qualquer identificador no parâmetro idtransaction:

ID da Cobrança KavroPay: ex: PAY9B1DEB4D3B7D4BAD9BDD2B
ID do Saque KavroPay: ex: WIT7A28F1B3E4C9D01
Seu ID de Pedido (externalId): ex: ped_998811
ID da Transação Bancária / Adquirente: ex: E123456782026...

Consultar Status via GET

GET https://api.kavropay.com.br/v1/status?idtransaction={id} • escopo payments:read

Parâmetros de Query

Parâmetro	Tipo	Obrigatório	Descrição
`idtransaction`	string	Sim	ID KavroPay, seu ID externo ou ID da adquirente.

curl "https://api.kavropay.com.br/v1/status?idtransaction=PAY9B1DEB4D3B7D4BAD9BDD2B" \
  -H "Authorization: Bearer sk_live_SUA_CHAVE_AQUI"

const id = 'PAY9B1DEB4D3B7D4BAD9BDD2B';
const res = await fetch(`https://api.kavropay.com.br/v1/status?idtransaction=${id}`, {
  headers: { 'Authorization': 'Bearer sk_live_SUA_CHAVE_AQUI' }
});

const data = await res.json();
console.log('Status Atual:', data.status); // 'paid', 'waiting_payment', 'paid_out', etc.

import requests

id_tx = "PAY9B1DEB4D3B7D4BAD9BDD2B"
res = requests.get(
    f"https://api.kavropay.com.br/v1/status?idtransaction={id_tx}",
    headers={"Authorization": "Bearer sk_live_SUA_CHAVE_AQUI"}
)
print("Status:", res.json()["status"])

<?php
$id = "PAY9B1DEB4D3B7D4BAD9BDD2B";
$ch = curl_init("https://api.kavropay.com.br/v1/status?idtransaction=" . urlencode($id));
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: Bearer sk_live_SUA_CHAVE_AQUI"]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$res = json_decode(curl_exec($ch), true);
curl_close($ch);

echo "Status: " . $res["status"];

Resposta Rápida (HTTP 200 OK)

{
  "id": "PAY9B1DEB4D3B7D4BAD9BDD2B",
  "status": "paid"
}

Consultar Status via POST

Para clientes que preferem enviar payloads em JSON no corpo da requisição: POST https://api.kavropay.com.br/v1/status • escopo payments:read

curl -X POST https://api.kavropay.com.br/v1/status \
  -H "Authorization: Bearer sk_live_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{"idtransaction": "ped_998811"}'

Possíveis Valores de Retorno (`status`)

Status Retornado	Significado
`waiting_payment`	Cobrança gerada e aguardando transferência PIX.
`paid`	Cobrança PIX paga e confirmada.
`expired`	Validade da cobrança expirou.
`cancelled`	Cobrança cancelada pelo lojista.
`pending`	Saque em fila de processamento.
`processing`	Saque enviado para liquidação no SPI.
`paid_out` / `completed`	Saque liquidado com sucesso na conta de destino.
`failed`	Saque falhou e o saldo foi estornado.

Primeiros Passos

Endpoints API

Infraestrutura

Referência

Verificação de Status Unificado

Como Funciona

Consultar Status via GET

Parâmetros de Query

Consultar Status via POST

Possíveis Valores de Retorno (`status`)

Como Funciona

Consultar Status via GET

Parâmetros de Query

Consultar Status via POST

Possíveis Valores de Retorno (status)

Possíveis Valores de Retorno (`status`)