Consultar pagamento e status do pedido

POST /api/v1/order/status

Solicitar autenticação

Inclui X-Bolt-Key, X-Bolt-Timestamp e X-Bolt-Signature. Use um timestamp atual em milissegundos e assine timestamp junto com o corpo exato da solicitação.

01. Parâmetros de solicitação

application/json

externalOrderIdObrigatório

String

Envie ao comerciante externalOrderId usado ao criar o pedido, não orderToken. Somente pedidos pertencentes à chave API atual podem ser consultados.

Valor de exemplo

{"externalOrderId": "INV-20260209-99281"}

Sequência obrigatória, de 6 a 64 caracteres. Letras, dígitos, sublinhados (_) e hífens (-) são permitidos.

Body

Estados do pedido e atendimento

PENDING

Aguardando pagamento: nenhuma transferência qualificada foi correspondida.

PAID

Pagamento detectado, aguardando confirmação do blockchain.

CONFIRMED

Pagamento confirmado ou aceito através da análise do comerciante; a entrega do retorno de chamada ainda pode estar pendente.

COMPLETED

Pagamento confirmado e BoltUtil recebeu uma resposta de retorno de chamada bem-sucedida.

EXPIRED

O período de pagamento terminou sem uma transferência qualificada correspondente. Uma transferência dentro do prazo com confirmação atrasada ainda poderá ser reconhecida posteriormente.

FAILED

O pedido está em estado de falha. Não trate isso como sucesso no pagamento.

CANCELLED

O pedido foi cancelado. Não trate isso como sucesso no pagamento.

PAID indica confirmação pendente; não entregue com base apenas nesse estado. CONFIRMED ou COMPLETED indicam pagamento confirmado; entregue apenas uma vez por externalOrderId. COMPLETED significa que BoltUtil recebeu uma resposta bem-sucedida à notificação, não que seu negócio entregou o pedido. Em pagamentos revisados manualmente, confira também o valor pago e o tipo de liquidação.

02. Campos de resposta (data)

application/json

statusString

Estado atual do pedido. Veja as descrições dos estados acima; um pedido não precisa passar por todos os estados.

amountString

O valor do pedido a pagar, retornado como uma string. Use paidAmount para o valor pago registrado.

paidAmountString / null

Valor pago registrado como uma string; pode ser null antes do pagamento. Para pedidos pagos mais antigos sem um valor pago separado, o valor será o valor a pagar.

shortfallAmountString / null

Deficiência registrada como uma string; pode ser null antes do pagamento. Pagamentos indevidos aceitos manualmente podem retornar 0 aqui. Para calcular uma diferença sinalizada, subtraia paidAmount de amount.

settlementTypeString / null

EXACT: correspondência exata; MANUAL_UNDERPAID: pagamento insuficiente aceito; MANUAL_OVERPAID: pagamento a maior aceito; MANUAL_AMBIGUOUS: outra associação revisada manualmente. Pode ser null antes da liquidação.

paymentRouteString / null

Rota efetiva: DIRECT para transferência direta, SPLIT para pagamento dividido. Consultas podem retornar null antes da liquidação; não confirma pagamento.

platformFeeString / null

Taxa efetiva da plataforma em currency, como string; pode ser null antes do registro. Pagamentos diretos ou isentos: 0. Não inclui taxa de rede.

merchantNetAmountString / null

Valor líquido do comerciante em currency, como string. Na divisão: total pago menos taxa. Pode ser null antes do registro; callbacks históricos podem usar o valor pago.

manuallyAcceptedBoolean

Atualmente true apenas para MANUAL_UNDERPAID. Não identifica todas as ações manuais; use settlementType para o tipo específico.

externalOrderIdString

Pedido do comerciante ID fornecido na criação, usado para consultar e associar seu pedido comercial.

txHashString / null

Hash da transação do pagamento associado; pode ser null antes da associação. Um hash por si só não prova a confirmação do pagamento.

destinationAddressString

A carteira de recebimento do comerciante usada por este pedido; vários pedidos podem compartilhá-lo.

confirmationsInteger / null

Contagem de confirmação de blockchain registrada; pode ser null. As regras de confirmação variam de acordo com a rede. Use status para determinar a confirmação do pagamento.

currencyString

Código da moeda de pagamento, como USDT ou USDC.

networkString

Código da rede de pagamento: TRC20, ERC20, BEP20, POLYGON, SOLANA ou BASE.

paidAtString / null

Tempo de pagamento registrado como uma sequência de data e hora; null antes que um pagamento seja registrado.

confirmedAtString / null

Tempo de confirmação de pagamento registrado como uma sequência de data e hora; null antes da confirmação.

completedAtString / null

Hora em que o pedido foi inserido pela primeira vez COMPLETED, como uma string de data e hora; null antes da conclusão. A repetição da entrega bem-sucedida não a substitui. Os pedidos concluídos anteriormente mantêm o tempo histórico registrado.

metadataObject

Objeto JSON personalizado fornecido na criação do pedido. Não é usado para correspondência de pagamentos.

Notas de consulta

A consulta retorna o estado do pedido armazenado; ele não verifica imediatamente o blockchain. As confirmações são valores registrados. Use status para determinar a confirmação do pagamento.
Sem pagamento combinado, paidAmount, shortfallAmount, settlementType, txHash e horários relacionados podem ser null. Isto não é uma falha de consulta.
Somente seus próprios pedidos podem ser consultados. Contas gratuitas podem acessar pedidos criados nos últimos 30 dias; membros ativos podem acessar todo o histórico. Pedidos ausentes ou inacessíveis, pedido de devolução não encontrado.
paidAt, confirmedAt e completedAt são strings de data e hora, como 2026-02-09T18:20:50.790, sem deslocamento de fuso horário. Eles não são carimbos de data/hora em milissegundos.

Erros comuns

Estes são casos comuns. Use o status real do HTTP e o código/mensagem de resposta para diagnosticar falhas. Uma resposta de erro não é um resultado de pagamento.

401: Verifique a chave API, a assinatura do corpo bruto e o milissegundo atual timestamp (dentro de 5 minutos do relógio do servidor).
404: O pedido está faltando, pertence a outro comerciante ou está fora do histórico permitido pelo seu plano.