Documentation développeur

Consulter le paiement et le statut de la commande

Consultez par identifiant marchand. Distinguez confirmation, remise de notification et livraison de commande.

POST /api/v1/order/status

Demander une authentification

Inclut X-Bolt-Key, X-Bolt-Timestamp et X-Bolt-Signature. Utilisez une milliseconde actuelle de timestamp et signez le timestamp avec le corps exact de la demande.

01. Paramètres de la requête

application/json
externalOrderIdObligatoire
String

Envoyer le marchand externalOrderId utilisé lors de la création de la commande, et non orderToken. Seules les commandes appartenant à la clé API actuelle peuvent être interrogées.

Exemple de valeur

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

Chaîne obligatoire, 6 à 64 caractères. Les lettres, chiffres, traits de soulignement (_) et tirets (-) sont autorisés.

Body

États et exécution des commandes

PENDING

En attente de paiement : aucun transfert éligible n'a été correspondant.

PAID

Paiement détecté, en attente de confirmation blockchain.

CONFIRMED

Paiement confirmé ou accepté via l'examen du marchand ; La livraison du rappel est peut-être toujours en attente.

COMPLETED

Paiement confirmé et BoltUtil a reçu une réponse de rappel réussie.

EXPIRED

La fenêtre de paiement s'est terminée sans transfert éligible correspondant. Un transfert à temps avec une confirmation retardée peut toujours être reconnu plus tard.

FAILED

La commande est en état d'échec. Ne considérez pas cela comme un succès de paiement.

CANCELLED

La commande a été annulée. Ne considérez pas cela comme un succès de paiement.

PAID indique que la confirmation est en attente ; ne livrez pas sur cette seule base. CONFIRMED ou COMPLETED indiquent un paiement confirmé ; ne livrez qu’une fois par externalOrderId. COMPLETED signifie que BoltUtil a reçu une réponse positive à la notification, sans prouver que votre entreprise a livré la commande. Pour les paiements examinés manuellement, vérifiez aussi le montant payé et le type de règlement.

02. Champs de réponse (data)

application/json
statusString
État actuel de la commande. Voir les descriptions d'état ci-dessus ; une commande n'a pas besoin de passer par tous les États.
amountString
Le montant de la commande à payer, renvoyé sous forme de chaîne. Utilisez paidAmount pour le montant payé enregistré.
paidAmountString / null
Montant payé enregistré sous forme de chaîne ; peut être null avant le paiement. Pour les commandes payées plus anciennes sans montant à payer distinct, il revient au montant à payer.
shortfallAmountString / null
Déficit enregistré sous forme de chaîne ; peut être null avant le paiement. Les trop-payés acceptés manuellement peuvent renvoyer 0 ici. Pour calculer une différence signée, soustrayez paidAmount de amount.
settlementTypeString / null
EXACT : correspondance exacte ; MANUAL_UNDERPAID : sous-paiement accepté ; MANUAL_OVERPAID : trop-payé accepté ; MANUAL_AMBIGUOUS : une autre association révisée manuellement. Peut être null avant règlement.
paymentRouteString / null
Circuit réel : DIRECT pour un transfert direct, SPLIT pour un paiement réparti. Peut être null dans une requête avant règlement ; ne prouve pas la confirmation.
platformFeeString / null
Frais réels de plateforme en currency, sous forme de chaîne ; null possible avant enregistrement. Paiements directs ou exonérés : 0. Hors frais réseau.
merchantNetAmountString / null
Encaissement net du marchand en currency, sous forme de chaîne. En répartition : total payé moins frais. Une valeur null est possible avant enregistrement ; les anciens callbacks peuvent utiliser le montant payé.
manuallyAcceptedBoolean
Actuellement true uniquement pour MANUAL_UNDERPAID. Il n'identifie pas chaque action manuelle ; utilisez settlementType pour le type spécifique.
externalOrderIdString
Commande marchand ID fournie à la création, utilisée pour interroger et associer votre commande commerciale.
txHashString / null
Hash de transaction du paiement associé ; peut être null avant association. Un hachage à lui seul ne prouve pas la confirmation du paiement.
destinationAddressString
Le portefeuille de réception du commerçant utilisé par cette commande ; plusieurs commandes peuvent le partager.
confirmationsInteger / null
Nombre de confirmations de blockchain enregistrées ; peut être null. Les règles de confirmation diffèrent selon le réseau. Utilisez status pour déterminer la confirmation du paiement.
currencyString
Code de devise de paiement, tel que USDT ou USDC.
networkString
Code réseau de paiement : TRC20, ERC20, BEP20, POLYGON, SOLANA ou BASE.
paidAtString / null
Heure de paiement enregistrée sous forme de chaîne date-heure ; null avant qu'un paiement ne soit enregistré.
confirmedAtString / null
Heure de confirmation de paiement enregistrée sous forme de chaîne date-heure ; null avant confirmation.
completedAtString / null
Heure de la première commande saisie COMPLETED, sous forme de chaîne date-heure ; null avant la fin. Une livraison répétée réussie ne l’écrase pas. Les commandes précédemment terminées conservent leur heure d'enregistrement historique.
metadataObject
Objet JSON personnalisé fourni lors de la création de la commande. Il n'est pas utilisé pour le rapprochement des paiements.

Notes sur les requêtes

  • La requête renvoie l'état de la commande stockée ; il n'analyse pas immédiatement la blockchain. Les confirmations sont des valeurs enregistrées. Utilisez status pour déterminer la confirmation du paiement.
  • Sans paiement correspondant, paidAmount, shortfallAmount, settlementType, txHash et les heures associées peuvent être null. Il ne s'agit pas d'un échec de requête.
  • Seules vos propres commandes peuvent être interrogées. Les comptes gratuits peuvent accéder aux commandes créées au cours des 30 derniers jours ; les membres actifs peuvent accéder à tout l’historique. Commandes manquantes ou inaccessibles, commande de retour introuvable.
  • paidAt, confirmedAt et completedAt sont des chaînes date-heure, telles que 2026-02-09T18:20:50.790, sans décalage de fuseau horaire. Ce ne sont pas des horodatages en millisecondes.

Erreurs courantes

Ce sont des cas courants. Utilisez l'état actuel du HTTP et le code/message de réponse pour diagnostiquer les pannes. Une réponse d'erreur n'est pas un résultat de paiement.

  • 401 : Vérifiez la clé API, la signature du corps brut et la milliseconde actuelle du timestamp (dans les 5 minutes suivant l'horloge du serveur).
  • 404 : La commande est manquante, appartient à un autre commerçant ou est en dehors de l'historique autorisé par votre forfait.
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"

Les adresses, les hachages de transactions et les commandes en sont des exemples. Remplacez-les par votre propre test data.

Base URL

PROD
https://api.boltutil.com