Documentación para desarrolladores

Consultar el pago y el estado del pedido

Consulta por el ID del comerciante. Distingue confirmación, entrega de notificaciones y entrega del pedido.

POST /api/v1/order/status

Solicitar autenticación

Incluye X-Bolt-Key, X-Bolt-Timestamp y X-Bolt-Signature. Utilice un timestamp actual de milisegundos y firme el timestamp junto con el cuerpo exacto de la solicitud.

01. Parámetros de solicitud

application/json
externalOrderIdObligatorio
String

Envíe el comerciante externalOrderId utilizado al crear el pedido, no orderToken. Solo se pueden consultar los pedidos que pertenecen a la clave API actual.

Valor de ejemplo

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

Cadena obligatoria, entre 6 y 64 caracteres. Se permiten letras, dígitos, guiones bajos (_) y guiones (-).

Body

Estados y cumplimiento del pedido

PENDING

En espera de pago: no se ha igualado ninguna transferencia elegible.

PAID

Pago detectado, en espera de confirmación de blockchain.

CONFIRMED

Pago confirmado o aceptado mediante revisión del comerciante; Es posible que la entrega de devolución de llamada aún esté pendiente.

COMPLETED

Pago confirmado y BoltUtil recibió una respuesta de devolución de llamada exitosa.

EXPIRED

La ventana de pago finalizó sin una transferencia elegible igualada. Es posible que una transferencia puntual con confirmación retrasada se reconozca más adelante.

FAILED

El pedido se encuentra en un estado fallido. No lo trate como un pago exitoso.

CANCELLED

El pedido fue cancelado. No lo trate como un pago exitoso.

PAID indica que falta la confirmación; no entregues el pedido basándote en ese estado. CONFIRMED o COMPLETED indican pago confirmado; entrega solo una vez por externalOrderId. COMPLETED significa que BoltUtil recibió una respuesta correcta a la notificación, no que tu negocio haya entregado el pedido. En pagos revisados manualmente, comprueba también el importe pagado y el tipo de liquidación.

02. Campos de respuesta (data)

application/json
statusString
Estado del pedido actual. Consulte las descripciones de los estados anteriores; una orden no tiene por qué pasar por todos los estados.
amountString
El importe del pedido a pagar, devuelto como una cadena. Utilice paidAmount para obtener el monto pagado registrado.
paidAmountString / null
Monto pagado registrado como una cadena; Puede ser null antes del pago. Para pedidos pagados más antiguos sin un monto pagado por separado, vuelve al monto a pagar.
shortfallAmountString / null
Déficit registrado como una cadena; puede ser null antes del pago. Los pagos en exceso aceptados manualmente pueden devolver 0 aquí. Para calcular una diferencia con signo, reste paidAmount de amount.
settlementTypeString / null
EXACT: coincidencia exacta; MANUAL_UNDERPAID: pago insuficiente aceptado; MANUAL_OVERPAID: sobrepago aceptado; MANUAL_AMBIGUOUS: otra asociación revisada manualmente. Puede ser null antes de la liquidación.
paymentRouteString / null
Ruta real: DIRECT para transferencia directa, SPLIT para pago dividido. Puede ser null en consultas antes de liquidar; no confirma el pago.
platformFeeString / null
Comisión real de plataforma en currency, como cadena; puede ser null si aún no consta. Pagos directos o exentos: 0. No incluye gastos de red.
merchantNetAmountString / null
Neto del comerciante en currency, como cadena. En pagos divididos: total pagado menos comisión. Puede ser null antes del registro; callbacks históricos pueden usar el importe pagado.
manuallyAcceptedBoolean
Actualmente true solo para MANUAL_UNDERPAID. No identifica cada acción manual; utilice settlementType para el tipo específico.
externalOrderIdString
Pedido comercial ID proporcionado en el momento de la creación, utilizado para consultar y asociar su pedido comercial.
txHashString / null
Hash de transacción del pago asociado; puede ser null antes de la asociación. Un hash por sí solo no prueba la confirmación del pago.
destinationAddressString
El comerciante que recibe la billetera utilizada por este pedido; varios pedidos pueden compartirlo.
confirmationsInteger / null
Recuento de confirmación de blockchain registrado; puede ser null. Las reglas de confirmación difieren según la red. Utilice status para determinar la confirmación del pago.
currencyString
Código de moneda de pago, como USDT o USDC.
networkString
Código de red de pago: TRC20, ERC20, BEP20, POLYGON, SOLANA o BASE.
paidAtString / null
Hora de pago registrada como una cadena de fecha y hora; null antes de que se registre un pago.
confirmedAtString / null
Hora de confirmación de pago registrada como una cadena de fecha y hora; null antes de la confirmación.
completedAtString / null
Hora en que se ingresó por primera vez el pedido COMPLETED, como una cadena de fecha y hora; null antes de finalizar. La entrega repetida exitosa no la sobrescribe. Los pedidos completados anteriormente conservan su tiempo histórico registrado.
metadataObject
Objeto JSON personalizado proporcionado en la creación del pedido. No se utiliza para igualar pagos.

Notas de consulta

  • La consulta devuelve el estado del pedido almacenado; no escanea inmediatamente la cadena de bloques. Las confirmaciones son valores registrados. Utilice status para determinar la confirmación del pago.
  • Sin un pago coincidente, paidAmount, shortfallAmount, settlementType, txHash y tiempos relacionados pueden ser null. Esto no es un error de consulta.
  • Solo se pueden consultar sus propios pedidos. Las cuentas gratuitas pueden acceder a los pedidos creados en los últimos 30 días; Los miembros activos pueden acceder a todo el historial. Pedidos faltantes o inaccesibles. No se encontró el pedido de devolución.
  • paidAt, confirmedAt y completedAt son cadenas de fecha y hora, como 2026-02-09T18:20:50.790, sin desplazamiento de zona horaria. No son marcas de tiempo de milisegundos.

Errores comunes

Estos son casos comunes. Utilice el estado actual de HTTP y el código/mensaje de respuesta para diagnosticar fallas. Una respuesta de error no es un resultado de pago.

  • 401: verifique la clave API, la firma del cuerpo sin formato y el milisegundo actual timestamp (dentro de los 5 minutos del reloj del servidor).
  • 404: el pedido falta, pertenece a otro comerciante o está fuera del historial permitido por su plan.
status / cURL
# Run against your account only when ready; this sends an API request.
: "${BOLTUTIL_API_KEY:?Set your complete API Key}"
: "${BOLTUTIL_WEBHOOK_SECRET:?Set your Webhook secret}"
timestamp=$(python3 -c 'import time; print(int(time.time()*1000))')
body='{"externalOrderId":"INV-20260209-99281"}'
signature=$(printf '%s.%s' "$timestamp" "$body" | openssl dgst -sha256 -hmac "$BOLTUTIL_WEBHOOK_SECRET" | awk '{print $NF}')

curl --request POST "https://api.boltutil.com/api/v1/order/status" \
  --header 'Content-Type: application/json' \
  --header "X-Bolt-Key: $BOLTUTIL_API_KEY" \
  --header "X-Bolt-Timestamp: $timestamp" \
  --header "X-Bolt-Signature: $signature" \
  --data-binary "$body"

Direcciones, hashes de transacciones y pedidos son ejemplos. Reemplácelos con su propia prueba data.

Base URL

PROD
https://api.boltutil.com